AwesomeAdam54321/inweb-bootstrap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documented and revised patterns

Browse source
This commit is contained in:
Graham Nelson 2020-04-22 23:57:09 +01:00
parent 9e86ae9c26
commit 34f4ac213d
106 changed files with 3299 additions and 3177 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

200
Chapter 1/Patterns.w
View file

@ -16,20 +16,23 @@ typedef struct weave_pattern {
struct weave_format *pattern_format; /* such as |DVI|: the desired final format */
struct linked_list *plugins; /* of |weave_plugin|: any extras needed */
struct linked_list *colour_schemes; /* of |colour_scheme|: any extras needed */
struct linked_list *payloads; /* of |text_stream|: leafnames of associated files */
struct linked_list *up_payloads; /* of |text_stream|: leafnames of associated files */
struct text_stream *mathematics_plugin; /* name only, not a |weave_pattern *| */
struct text_stream *footnotes_plugin; /* name only, not a |weave_pattern *| */
struct text_stream *tex_command; /* shell command to use for |tex| */
struct text_stream *pdftex_command; /* shell command to use for |pdftex| */
struct text_stream *open_command; /* shell command to use for |open| */
int embed_CSS; /* embed CSS directly into any HTML files made? */
int hierarchical; /* weave as one part of a collection of woven webs */
int show_abbrevs; /* show section range abbreviations in the weave? */
int number_sections; /* insert section numbers into the weave? */
struct text_stream *default_range; /* for example, |sections| */
struct web *patterned_for; /* the web which caused this to be read in */
int commands;
int name_command_given;
MEMORY_MANAGEMENT
} weave_pattern;
@ -50,18 +53,18 @@ weave_pattern *Patterns::find(web *W, text_stream *name) {
wp->pattern_location = NULL;
wp->plugins = NEW_LINKED_LIST(weave_plugin);
wp->colour_schemes = NEW_LINKED_LIST(colour_scheme);
wp->payloads = NEW_LINKED_LIST(text_stream);
wp->up_payloads = NEW_LINKED_LIST(text_stream);
wp->based_on = NULL;
wp->embed_CSS = FALSE;
wp->hierarchical = FALSE;
wp->patterned_for = W;
wp->show_abbrevs = TRUE;
wp->number_sections = FALSE;
wp->footnotes_plugin = NULL;
wp->mathematics_plugin = NULL;
wp->default_range = Str::duplicate(I"0");
wp->tex_command = Str::duplicate(I"tex");
wp->pdftex_command = Str::duplicate(I"pdftex");
wp->open_command = Str::duplicate(I"open");
wp->commands = 0;
wp->name_command_given = FALSE;
@<Locate the pattern directory@> =
wp->pattern_location = NULL;
@ -92,6 +95,8 @@ weave_pattern *Patterns::find(web *W, text_stream *name) {
TRUE, Patterns::scan_pattern_line, NULL, wp);
if (wp->pattern_format == NULL)
Errors::fatal_with_text("pattern did not specify a format", name);
if (wp->name_command_given == FALSE)
Errors::fatal_with_text("pattern did not name itself at the top", name);
@ The Foundation module provides a standard way to scan text files line by
line, and this is used to send each line in the |pattern.txt| file to the
@ -100,82 +105,75 @@ following routine:
=
void Patterns::scan_pattern_line(text_stream *line, text_file_position *tfp, void *X) {
weave_pattern *wp = (weave_pattern *) X;
Str::trim_white_space(line); /* ignore trailing space */
if (Str::len(line) == 0) return; /* ignore blank lines */
if (Str::get_first_char(line) == '#') return; /* lines opening with |#| are comments */
wp->commands++;
match_results mr = Regexp::create_mr();
if (Regexp::match(&mr, line, L" *from (%c+)")) @<This is a from command@>;
if (Regexp::match(&mr, line, L" *(%c+?) = (%c+)")) @<This is an X = Y command@>;
if (Regexp::match(&mr, line, L" *embed css *")) @<This is an embed CSS command@>;
if (Regexp::match(&mr, line, L" *hierarchical *")) @<This is a hierarchical command@>;
if (Regexp::match(&mr, line, L" *plugin (%c+)")) @<This is a plugin command@>;
if (Regexp::match(&mr, line, L" *use (%c+)")) @<This is a use command@>;
if (Regexp::match(&mr, line, L" *use-up (%c+)")) @<This is a use-up command@>;
if (Regexp::match(&mr, line, L" *%C%c*"))
Errors::in_text_file("unrecognised pattern command", tfp);
Regexp::dispose_of(&mr);
}
@<This is a from command@> =
wp->based_on = Patterns::find(wp->patterned_for, mr.exp[0]);
Regexp::dispose_of(&mr);
return;
@<This is an X = Y command@> =
if (Str::eq(mr.exp[0], I"format")) {
wp->pattern_format = Formats::find_by_name(mr.exp[1]);
} else if (Str::eq(mr.exp[0], I"abbrevs")) {
wp->show_abbrevs = Patterns::yes_or_no(mr.exp[1], tfp);
} else if (Str::eq(mr.exp[0], I"numbered")) {
wp->number_sections = Patterns::yes_or_no(mr.exp[1], tfp);
} else if (Str::eq(mr.exp[0], I"default-range")) {
wp->default_range = Str::duplicate(mr.exp[1]);
} else if (Str::eq(mr.exp[0], I"tex-command")) {
wp->tex_command = Str::duplicate(mr.exp[1]);
} else if (Str::eq(mr.exp[0], I"pdftex-command")) {
wp->pdftex_command = Str::duplicate(mr.exp[1]);
} else if (Str::eq(mr.exp[0], I"open-command")) {
wp->open_command = Str::duplicate(mr.exp[1]);
} else if ((Bibliographic::data_exists(wp->patterned_for->md, mr.exp[0])) ||
(Str::eq(mr.exp[0], I"Booklet Title"))) {
Bibliographic::set_datum(wp->patterned_for->md, mr.exp[0], mr.exp[1]);
if (Regexp::match(&mr, line, L"(%c+) *: *(%c+?)")) {
text_stream *key = mr.exp[0], *value = Str::duplicate(mr.exp[1]);
if ((Str::eq_insensitive(key, I"name")) && (wp->commands == 1)) {
match_results mr2 = Regexp::create_mr();
if (Regexp::match(&mr2, value, L"(%c+?) based on (%c+)")) {
if (Str::ne_insensitive(mr2.exp[0], wp->pattern_name)) {
Errors::in_text_file("wrong pattern name", tfp);
}
wp->based_on = Patterns::find(wp->patterned_for, mr2.exp[1]);
wp->pattern_format = wp->based_on->pattern_format;
wp->embed_CSS = wp->based_on->embed_CSS;
wp->number_sections = wp->based_on->number_sections;
wp->default_range = Str::duplicate(wp->based_on->default_range);
wp->mathematics_plugin = Str::duplicate(wp->based_on->mathematics_plugin);
wp->footnotes_plugin = Str::duplicate(wp->based_on->footnotes_plugin);
} else {
if (Str::ne_insensitive(value, wp->pattern_name)) {
Errors::in_text_file("wrong pattern name", tfp);
}
}
Regexp::dispose_of(&mr2);
wp->name_command_given = TRUE;
} else if (Str::eq_insensitive(key, I"plugin")) {
text_stream *name = Patterns::plugin_name(value, tfp);
if (Str::len(name) > 0) {
weave_plugin *plugin = WeavePlugins::new(name);
ADD_TO_LINKED_LIST(plugin, weave_plugin, wp->plugins);
}
} else if (Str::eq_insensitive(key, I"format")) {
wp->pattern_format = Formats::find_by_name(value);
} else if (Str::eq_insensitive(key, I"embed CSS")) {
wp->embed_CSS = Patterns::yes_or_no(value, tfp);
} else if (Str::eq_insensitive(key, I"number sections")) {
wp->number_sections = Patterns::yes_or_no(value, tfp);
} else if (Str::eq_insensitive(key, I"default range")) {
wp->default_range = Str::duplicate(value);
} else if (Str::eq_insensitive(key, I"mathematics plugin")) {
wp->mathematics_plugin = Patterns::plugin_name(value, tfp);
} else if (Str::eq_insensitive(key, I"footnotes plugin")) {
wp->footnotes_plugin = Patterns::plugin_name(value, tfp);
} else if (Str::eq_insensitive(key, I"TeX command")) {
wp->tex_command = Str::duplicate(value);
} else if (Str::eq_insensitive(key, I"PDFTeX command")) {
wp->pdftex_command = Str::duplicate(value);
} else if (Str::eq_insensitive(key, I"open command")) {
wp->open_command = Str::duplicate(value);
} else if (Str::eq_insensitive(key, I"bibliographic data")) {
match_results mr2 = Regexp::create_mr();
if (Regexp::match(&mr2, value, L"(%c+?) = (%c+)")) {
Bibliographic::set_datum(wp->patterned_for->md, mr2.exp[0], mr2.exp[1]);
} else {
Errors::in_text_file("syntax is 'bibliographic data: X = Y'", tfp);
}
Regexp::dispose_of(&mr2);
} else {
Errors::in_text_file("unrecognised pattern command", tfp);
}
} else {
PRINT("Setting: %S\n", mr.exp[0]);
Errors::in_text_file("no such pattern setting", tfp);
Errors::in_text_file("unrecognised pattern command", tfp);
}
Regexp::dispose_of(&mr);
return;
@<This is an embed CSS command@> =
wp->embed_CSS = TRUE;
Regexp::dispose_of(&mr);
return;
@<This is a hierarchical command@> =
wp->hierarchical = TRUE;
Regexp::dispose_of(&mr);
return;
@ "Plugins" here refer to //Weave Plugins//.
@<This is a plugin command@> =
weave_plugin *plugin = WeavePlugins::new(mr.exp[0]);
ADD_TO_LINKED_LIST(plugin, weave_plugin, wp->plugins);
Regexp::dispose_of(&mr);
return;
@ "Payloads" are associated files such as images which may be needed for an
HTML weave to look right. We identify them here only by leafname: their
actual location will depend on where the pattern directory is.
@<This is a use command@> =
text_stream *leafname = Str::duplicate(mr.exp[0]);
ADD_TO_LINKED_LIST(leafname, text_stream, wp->payloads);
Regexp::dispose_of(&mr);
return;
@<This is a use-up command@> =
text_stream *leafname = Str::duplicate(mr.exp[0]);
ADD_TO_LINKED_LIST(leafname, text_stream, wp->up_payloads);
Regexp::dispose_of(&mr);
return;
}
@ =
int Patterns::yes_or_no(text_stream *arg, text_file_position *tfp) {
@ -185,6 +183,18 @@ int Patterns::yes_or_no(text_stream *arg, text_file_position *tfp) {
return FALSE;
}
text_stream *Patterns::plugin_name(text_stream *arg, text_file_position *tfp) {
match_results mr = Regexp::create_mr();
if (Regexp::match(&mr, arg, L"(%i+)")) {
if (Str::eq_insensitive(arg, I"none")) return NULL;
} else {
Errors::in_text_file("plugin names must be single alphanumeric words", tfp);
arg = NULL;
}
Regexp::dispose_of(&mr);
return Str::duplicate(arg);
}
@h Obtaining files.
Patterns provide not merely some configuration settings (above): they also
provide template or style files of various kinds. When Inweb wants to find
@ -221,30 +231,6 @@ filename *Patterns::find_asset(weave_pattern *pattern, text_stream *dirname,
return NULL;
}
@ When we eventually want to deal with the |use P| commands, which call
for payloads to be copied into weave, we make good use of the above:
=
void Patterns::copy_payloads_into_weave(web *W, weave_pattern *pattern) {
text_stream *leafname;
LOOP_OVER_LINKED_LIST(leafname, text_stream, pattern->payloads) {
filename *F = Patterns::obtain_filename(pattern, leafname);
Patterns::copy_file_into_weave(W, F, NULL, NULL);
if (W->as_ebook) {
filename *rel = Filenames::in(NULL, leafname);
Epub::note_image(W->as_ebook, rel);
}
}
LOOP_OVER_LINKED_LIST(leafname, text_stream, pattern->up_payloads) {
filename *F = Patterns::obtain_filename(pattern, leafname);
Patterns::copy_up_file_into_weave(W, F, NULL);
if (W->as_ebook) {
filename *rel = Filenames::in(NULL, leafname);
Epub::note_image(W->as_ebook, rel);
}
}
}
@ =
typedef struct css_file_transformation {
struct text_stream *OUT;
@ -288,14 +274,6 @@ void Patterns::transform_CSS(text_stream *line, text_file_position *tfp, void *X
Regexp::dispose_of(&mr);
}
void Patterns::copy_up_file_into_weave(web *W, filename *F, pathname *P) {
pathname *H = W->redirect_weaves_to;
if (H == NULL) H = Reader::woven_folder(W);
H = Pathnames::up(H);
if (P) H = P;
Shell::copy(F, H, "");
}
@ =
void Patterns::include_plugins(OUTPUT_STREAM, web *W, weave_pattern *pattern, filename *from) {
for (weave_pattern *p = pattern; p; p = p->based_on) {

1
Chapter 1/Program Control.w
View file

@ -253,7 +253,6 @@ which for many small webs will be the entire thing.
Swarm::weave_subset(W, ins->chosen_range, shall_we_open, tag, pattern,
ins->weave_to_setting, ins->weave_into_setting,
ins->breadcrumb_setting, ins->navigation_setting);
Patterns::copy_payloads_into_weave(W, pattern);
} else {
Swarm::weave(W, ins->chosen_range, ins->swarm_mode, tag, pattern,
ins->weave_to_setting, ins->weave_into_setting,

1
Chapter 1/The Swarm.w
View file

@ -254,5 +254,4 @@ void Swarm::weave_index_templates(web *W, text_stream *range, weave_pattern *pat
Indexer::incorporate_template(OUT, W, range, INF, pattern, nav, crumbs);
STREAM_CLOSE(OUT);
}
Patterns::copy_payloads_into_weave(W, pattern);
}

56
Chapter 3/The Indexer.w
View file

@ -59,20 +59,13 @@ void Indexer::scan_cover_line(text_stream *line, text_file_position *tfp, void *
TEMPORARY_TEXT(matter);
Str::copy(matter, line);
match_results mr = Regexp::create_mr();
if ((include) &&
((state->target->self_contained) || (state->target->pattern->embed_CSS)) &&
(Regexp::match(&mr, matter, L" *%<link href=%\"(%c+?)\"%c*"))) {
filename *CSS_file = Patterns::obtain_filename(state->target->pattern, mr.exp[0]);
Indexer::transcribe_CSS(matter, CSS_file);
} else {
while (Regexp::match(&mr, matter, L"(%c*?)%[%[(%c*?)%]%](%c*)")) {
text_stream *left = mr.exp[0];
text_stream *command = mr.exp[1];
text_stream *right = mr.exp[2];
if (include) WRITE("%S", left);
@<Deal with a double-squares escape in a cover sheet@>;
Str::copy(matter, right);
}
while (Regexp::match(&mr, matter, L"(%c*?)%[%[(%c*?)%]%](%c*)")) {
text_stream *left = mr.exp[0];
text_stream *command = mr.exp[1];
text_stream *right = mr.exp[2];
if (include) WRITE("%S", left);
@<Deal with a double-squares escape in a cover sheet@>;
Str::copy(matter, right);
}
Regexp::dispose_of(&mr);
if (include) WRITE("%S\n", matter);
@ -91,8 +84,6 @@ void Indexer::scan_cover_line(text_stream *line, text_file_position *tfp, void *
Swarm::include_plugins(OUT, state->target->weave_web,
state->target, state->target->weave_to);
}
} else if (Str::eq_wide_string(command, L"Cover Sheet")) {
if (include) @<Weave in the parent pattern's cover sheet@>;
} else if (Regexp::match(&mr2, command, L"Navigation")) {
if (include) @<Weave in navigation@>;
} else if (Regexp::match(&mr2, command, L"Template (%c*?)")) {
@ -104,18 +95,6 @@ void Indexer::scan_cover_line(text_stream *line, text_file_position *tfp, void *
}
Regexp::dispose_of(&mr2);
@<Weave in the parent pattern's cover sheet@> =
if (state->target->pattern->based_on) {
weave_pattern *saved = state->target->pattern;
state->target->pattern = state->target->pattern->based_on;
Indexer::cover_sheet_maker(OUT, state->target->weave_web,
I"cover-sheet", state->target,
(state->halves & (WEAVE_FIRST_HALF + WEAVE_SECOND_HALF)));
state->target->pattern = saved;
} else {
Errors::in_text_file("cover sheet recursively includes itself", tfp);
}
@<Weave in navigation@> =
if (state->target->navigation) {
if (TextFiles::exists(state->target->navigation))
@ -250,12 +229,6 @@ void Indexer::run_engine(text_stream *OUT, index_engine_state *ies) {
if (Regexp::match(&mr, tl, L"(%c*?) ")) Str::copy(tl, mr.exp[0]); /* Strip trailing spaces */
if (TRACE_CI_EXECUTION)
@<Print line and contents of repeat stack@>;
if ((ies->nav_pattern->embed_CSS) &&
(Regexp::match(&mr, tl, L" *%<link href=%\"(%c+?)\"%c*"))) {
filename *CSS_file = Patterns::obtain_filename(ies->nav_pattern, mr.exp[0]);
Indexer::transcribe_CSS(OUT, CSS_file);
Str::clear(tl);
}
if ((Regexp::match(&mr, tl, L"%[%[(%c+)%]%]")) ||
(Regexp::match(&mr, tl, L" %[%[(%c+)%]%]"))) {
TEMPORARY_TEXT(command);
@ -718,21 +691,6 @@ void Indexer::list_module(OUTPUT_STREAM, module *M, int list_this) {
Indexer::list_module(OUT, N, TRUE);
}
@h Transcribing CSS.
=
void Indexer::transcribe_CSS(OUTPUT_STREAM, filename *CSS_file) {
WRITE("<style type=\"text/css\">\n");
TextFiles::read(CSS_file, FALSE, "can't open CSS file",
TRUE, Indexer::copy_CSS, NULL, OUT);
WRITE("\n</style>\n");
}
void Indexer::copy_CSS(text_stream *line, text_file_position *tfp, void *X) {
text_stream *OUT = (text_stream *) X;
WRITE("%S\n", line);
}
@h Tracking the file being written to.
=

19
Chapter 5/HTML Formats.w
View file

@ -520,18 +520,16 @@ that service uses to identify the video/audio in question.
@<Render footnote cue@> =
weave_footnote_cue_node *C = RETRIEVE_POINTER_weave_footnote_cue_node(N->content);
text_stream *fn_plugin_name =
Bibliographic::get_datum(hrs->wv->weave_web->md, I"Footnotes Plugin");
if (Str::ne_insensitive(fn_plugin_name, I"None"))
text_stream *fn_plugin_name = hrs->wv->pattern->footnotes_plugin;
if (Str::len(fn_plugin_name) > 0)
Swarm::ensure_plugin(hrs->wv, fn_plugin_name);
WRITE("<sup id=\"fnref:%S\"><a href=\"#fn:%S\" rel=\"footnote\">%S</a></sup>",
C->cue_text, C->cue_text, C->cue_text);
@<Render footnote@> =
weave_begin_footnote_text_node *C = RETRIEVE_POINTER_weave_begin_footnote_text_node(N->content);
text_stream *fn_plugin_name =
Bibliographic::get_datum(hrs->wv->weave_web->md, I"Footnotes Plugin");
if (Str::ne_insensitive(fn_plugin_name, I"None"))
text_stream *fn_plugin_name = hrs->wv->pattern->footnotes_plugin;
if (Str::len(fn_plugin_name) > 0)
Swarm::ensure_plugin(hrs->wv, fn_plugin_name);
WRITE("<li class=\"footnote\" id=\"fn:%S\"><p class=\"inwebfootnote\">", C->cue_text);
for (tree_node *M = N->child; M; M = M->next)
@ -576,10 +574,10 @@ that service uses to identify the video/audio in question.
WRITE("%S", C->content);
@<Render inline@> =
HTML_OPEN_WITH("code", "class=\"display\"");
HTML_OPEN_WITH("span", "class=\"extract\"");
for (tree_node *M = N->child; M; M = M->next)
Trees::traverse_from(M, &HTMLFormat::render_visit, (void *) hrs, L+1);
HTML_CLOSE("code");
HTML_CLOSE("span");
return FALSE;
@<Render locale@> =
@ -596,9 +594,8 @@ that service uses to identify the video/audio in question.
@<Render maths@> =
weave_maths_node *C = RETRIEVE_POINTER_weave_maths_node(N->content);
text_stream *plugin_name =
Bibliographic::get_datum(hrs->wv->weave_web->md, I"TeX Mathematics Plugin");
if (Str::eq_insensitive(plugin_name, I"None")) {
text_stream *plugin_name = hrs->wv->pattern->mathematics_plugin;
if (Str::len(plugin_name) == 0) {
TEMPORARY_TEXT(R);
TeX::remove_math_mode(R, C->content);
HTMLFormat::escape_text(OUT, R);

17
Chapter 5/TeX Format.w
View file

@ -245,11 +245,7 @@ to a given width, into the text at the current position.
if (C->in_code) WRITE("}");
@<Render toc@> =
weave_toc_node *C = RETRIEVE_POINTER_weave_toc_node(N->content);
if (trs->wv->pattern->show_abbrevs)
WRITE("\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont %S.", C->text1);
else
WRITE("\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont ");
WRITE("\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont ");
for (tree_node *M = N->child; M; M = M->next) {
Trees::traverse_from(M, &HTMLFormat::render_visit, (void *) trs, L+1);
if (M->next) WRITE("; ");
@ -377,10 +373,7 @@ void TeX::toc(weave_format *self, text_stream *OUT, weave_order *wv, int stage,
text_stream *text1, text_stream *text2, paragraph *P) {
switch (stage) {
case 1:
if (wv->pattern->show_abbrevs)
WRITE("\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont %S.", text1);
else
WRITE("\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont ");
WRITE("\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont ");
break;
case 2:
WRITE("; ");
@ -402,7 +395,6 @@ void TeX::chapter_title_page(weave_format *self, text_stream *OUT, weave_order *
LOOP_OVER_LINKED_LIST(S, section, C->sections) {
WRITE("\\smallskip\\noindent ");
if (wv->pattern->number_sections) WRITE("%d. ", S->printed_number);
if (wv->pattern->show_abbrevs) WRITE("|%S|: ", S->md->sect_range);
WRITE("{\\it %S}\\qquad\n%S", S->md->sect_title, S->sect_purpose);
}
}
@ -426,7 +418,7 @@ void TeX::paragraph_heading(weave_format *self, text_stream *OUT, weave_order *w
Str::clear(modified);
WRITE_TO(modified, "{\\sinchhigh %S}\\quad %S", mr.exp[0], mr.exp[1]);
}
if ((weight == 2) && ((S->md->is_a_singleton) || (wv->pattern->show_abbrevs == FALSE)))
if (weight == 2)
WRITE("\\%S{%S}{%S}{%S}{\\%S}{%S}%%\n",
TeX_macro, N, modified, mark, orn, NULL);
else
@ -492,8 +484,7 @@ in TeX's deeply peculiar font encoding system.
}
if (weight == 2) {
Str::copy(sectionmark, S->md->sect_title);
if (wv->pattern->show_abbrevs == FALSE) Str::clear(chaptermark);
else if (Str::len(S->md->sect_range) > 0) Str::copy(chaptermark, S->md->sect_range);
Str::clear(chaptermark);
if (Str::len(chaptermark) > 0) {
Str::clear(sectionmark);
WRITE_TO(sectionmark, " - %S", S->md->sect_title);

57
Chapter 5/Weave Plugins.w
View file

@ -102,28 +102,27 @@ void WeavePlugins::include_plugin(OUTPUT_STREAM, web *W, weave_plugin *wp,
Indexer::incorporate_template_for_web_and_pattern(OUT,
W, pattern, F);
} else {
Patterns::copy_file_into_weave(W, F, AP, NULL);
@<Use shell scripting to copy the file over@>;
}
} else {
if (html_mode) {
TEMPORARY_TEXT(ext);
Filenames::write_extension(ext, F);
if (Str::eq_insensitive(ext, I".css")) {
TEMPORARY_TEXT(url);
if (AP) Pathnames::relative_URL(url, Filenames::up(from), AP);
WRITE_TO(url, "%S", leafname);
WRITE("<link href=\"%S\" rel=\"stylesheet\" rev=\"stylesheet\" type=\"text/css\">\n", url);
DISCARD_TEXT(url);
}
if (Str::eq_insensitive(ext, I".js")) {
WeavePlugins::include_CSS_file(OUT, W, F, leafname, NULL, pattern, from);
} else if (Str::eq_insensitive(ext, I".js")) {
TEMPORARY_TEXT(url);
if (AP) Pathnames::relative_URL(url, Filenames::up(from), AP);
WRITE_TO(url, "%S", leafname);
WRITE("<script src=\"%S\"></script>\n", url);
DISCARD_TEXT(url);
@<Use shell scripting to copy the file over@>;
} else {
@<Use shell scripting to copy the file over@>;
}
} else {
@<Use shell scripting to copy the file over@>;
}
Patterns::copy_file_into_weave(W, F, AP, NULL);
}
finds++;
}
@ -141,13 +140,19 @@ void WeavePlugins::include_plugin(OUTPUT_STREAM, web *W, weave_plugin *wp,
DISCARD_TEXT(required);
}
@<Use shell scripting to copy the file over@> =
Patterns::copy_file_into_weave(W, F, AP, NULL);
if (W->as_ebook) {
filename *rel = Filenames::in(NULL, leafname);
Epub::note_image(W->as_ebook, rel);
}
@ =
void WeavePlugins::include_colour_scheme(OUTPUT_STREAM, web *W, colour_scheme *cs,
weave_pattern *pattern, filename *from) {
if (cs->last_included_in_round == current_inclusion_round) return;
cs->last_included_in_round = current_inclusion_round;
if (Str::eq(pattern->pattern_format->format_name, I"HTML")) {
pathname *AP = Colonies::assets_path();
TEMPORARY_TEXT(css);
WRITE_TO(css, "%S.css", cs->scheme_name);
filename *F = Patterns::find_asset(pattern, I"Colouring", css);
@ -159,13 +164,33 @@ void WeavePlugins::include_colour_scheme(OUTPUT_STREAM, web *W, colour_scheme *c
Main::error_in_web(err, NULL);
DISCARD_TEXT(err);
} else {
TEMPORARY_TEXT(url);
if (AP) Pathnames::relative_URL(url, Filenames::up(from), AP);
WRITE_TO(url, "%S", css);
WRITE("<link href=\"%S\" rel=\"stylesheet\" rev=\"stylesheet\" type=\"text/css\">\n", url);
DISCARD_TEXT(url);
Patterns::copy_file_into_weave(W, F, AP, cs->prefix);
WeavePlugins::include_CSS_file(OUT, W, F, css, cs->prefix, pattern, from);
}
DISCARD_TEXT(css);
}
}
void WeavePlugins::include_CSS_file(OUTPUT_STREAM, web *W, filename *F, text_stream *css,
text_stream *trans, weave_pattern *pattern, filename *from) {
if (pattern->embed_CSS) {
WRITE("<style type=\"text/css\">\n");
css_file_transformation cft;
cft.OUT = OUT;
cft.trans = trans;
TextFiles::read(F, FALSE, "can't open CSS file", TRUE,
Patterns::transform_CSS, NULL, (void *) &cft);
WRITE("</style>\n");
} else {
pathname *AP = Colonies::assets_path();
TEMPORARY_TEXT(url);
if (AP) Pathnames::relative_URL(url, Filenames::up(from), AP);
WRITE_TO(url, "%S", css);
WRITE("<link href=\"%S\" rel=\"stylesheet\" rev=\"stylesheet\" type=\"text/css\">\n", url);
DISCARD_TEXT(url);
Patterns::copy_file_into_weave(W, F, AP, trans);
if (W->as_ebook) {
filename *rel = Filenames::in(NULL, css);
Epub::note_image(W->as_ebook, rel);
}
}
}

421
Manual/Advanced Weaving with Patterns.w
View file

@ -1,129 +1,305 @@
Advanced Weaving with Patterns.
Customise the booklets woven from a web.
Customise your weave by creating a new pattern.
@h Weave patterns.
As noted, the two most useful weave patterns are |-weave-as HTML| and
|-weave-as TeX|, and these are both supplied built in to Inweb. When you
weave something with |-weave-as P|, for some pattern name |P|, Inweb first
looks to see if the web in question defines a custom pattern of that name.
For example,
@h Patterns versus formats.
Every weave produces output in a "format". The formats are built in to Inweb,
and adding new ones would mean contributing code to the project: currently
we have HTML, ePub, Plain Text, PDF, DIV, and TeX.
There is no way to specify the format at the command line. That's because
|-weave-as P| tells Inweb to weave with a given "pattern": a weave pattern
combines a choice of format with other settings to produce a customised
weave. Patterns can also be based on other patterns: one can, in effect, say
"I want something like P but with some differences". For example, the Inweb
manual at GitHub is woven with |-weave-as GitHubPages|, which is a pattern
based heavily on a generic website-producing pattern called |HTML|.
The upshot of all this is that if you want a website, but one which looks and
behaves differently from what |-weave-as HTML| would give, you should create
a new pattern based on it, and work from there. But patterns are not just
for websites.
@ A pattern definition is a directory containing various files, which we'll
get to in due course. Inweb looks for patterns in three places in turn:
(a) The location given by the |patterns| command in the current colony file,
if there is one: see //Making Weaves into Websites//.
(b) The |Patterns| subdirectory of the current web, if there is a current web,
and if it has such a subdirectory.
(c) The set of built-in patterns supplied with Inweb, at |inweb/Patterns|
in the usual distribution.
For example, the command
= (text as ConsoleText)
$ inweb/Tangled/inweb inweb/Examples/goldbach -weave-as Tapestry
=
would look for a directory called:
= (text)
inweb/Examples/goldbach/Patterns/Tapestry
=
If that is found, Inweb expects it to define |Tapestry|. If not, Inweb next
tries:
= (text)
inweb/Patterns/Tapestry
=
since |inweb/Patterns| is where the built-in patterns are kept. If it can't
find either, Inweb issues an error.
didn't set a colony file, so (a) doesn't apply. Inweb first tries
|inweb/Examples/goldbach/Patterns/Tapestry| and then |inweb/Patterns/Tapestry|.
If it can't find either, Inweb issues an error.
@ Patterns are a relatively new feature of Inweb, but allow for considerable
customisation of the woven output. In brief, a pattern directory is expected
to contain a configuration file called |pattern.txt|. This consists of a
series of simple one-line commands.
@h Basic settings.
Patterns allow for extensive customisation of the woven output, especially
through the use of plugins (see below). But they can also be extremely minimal.
The one absolute requirement is to include a configuration file called
|pattern.txt|, which consists of a series of simple one-line commands.
In this file, blank lines, leading and trailing white space are all ignored,
as is any file whose first character is |#|.
Most custom patterns open with the command:
= (text)
from Whatever
=
which tells Inweb that this new pattern inherits from an existing one named
|Whatever|. (Do not get these into loops, with A inheriting from B and B
also inheriting from A.) The rule is then that if Inweb needs a file to do
with weaving, it looks first in the new custom pattern, and then, failing
that, in the pattern inherited from. As a result, the custom pattern need
only contain actual differences.
There should then always be a command reading:
= (text)
format = HTML
=
or whatever other file format is required (for the TeX pattern, for example,
this reads |format = PDF|). A few other settings can also be made with |=|.
(a) |numbered = yes| causes the weaver to apply numbers to section headings:
the first included will be number 1, and so on. Default is |no|.
(b) |abbrevs = no| causes the weaver to suppress all mention of abbreviated
sections ranges, such as |2/tpc|, which aren't useful for documentation (for
example). Default is |yes|.
(c) |tex-command = C| tells the weaver that the TeX typesetting system should
be invoked with the shell command |C|. Default is |tex|.
(d) |pdftex-command = C| tells the weaver that the TeX typesetting system should
be invoked with the shell command |C| when what we want is a PDF, not a DVI
file. Default is |pdftex|.
(e) |open-command = C| tells the weaver to use the shell command |C| if it
wants to open the woven file (i.e., on the user's computer) after it finishes.
Default is |open|, which works nicely for MacOS.
(f) |default-range = R| tells the weaver to assume the range |R|, if the user
tries to weave a multi-section web with this pattern. (For example, the standard
HTML pattern sets |default-range = sections|.)
(g) The equals sign can also be used to override values of the bibliographic data
for the web. These changes are only temporary for the period in which the weave
is going on; they enable us to give custom titles to different weaves from the
same web. For example:
= (text)
Title = Grammar
Booklet Title = A formal grammar for Inform 7
Author = The Inform Project
=
@ The command:
= (text)
use X
=
tells Inweb that the file X, also stored in the pattern directory, should
be copied into any website being woven. For example, the HTML pattern says
= (text)
use crumbs.gif
=
to instruct Inweb that an image used by the pages generated needs to be
copied over.
Finally, the command
= (text)
embed css
=
tells Inweb that in any HTML file produced, the CSS necessary should be
embedded into the HTML, not linked as an external file. This is tidier for
patterns like TeX, where there will only be at most one HTML file produced,
and there's no need for an external CSS file.
@h Cover sheets.
If a weave has a range bigger than a single section -- for example, if it's
a weave of a chapter, or of the complete web -- then it will include a
"cover sheet". In the case of a PDF being made via TeX, this will actually
be an extra page at the front of the PDF; for HTML, of course, it will just
be additional material at the top of the web page.
The template for the cover sheet should be given in a file in the pattern
folder called |cover-sheet.tex|, |cover-sheet.html| or similar. Within it,
double-square brackets can be used to represent values from the bibliographic
data at the top of the web's Contents section. For example:
The first genuine line of the file should always give the pattern's name,
and say what if anything it is based on. For example, this might be:
= (text as Inweb)
\noindent{{\stitlefont [[Author]]}}
name: Tapestry based on HTML
=
In addition:
(a) |[[Cover Sheet]]| expands to the parent pattern's cover sheet -- this is
convenient if all you want to do is to add a note at the bottom of the
standard look.
(b) |[[Booklet Title]]| expands to text such as "Chapter 3", appropriate
to the weave being made.
(c) |[[Capitalized Title]]| is a form of the title in block capital letters.
That is the only compulsory content; with that one line in one file, the
Tapestry pattern is ready for use. (But of course it behaves identically
to HTML in every respect, so it's not very useful yet.)
Do not get these into loops, with A based on B and B based on A.
For a pattern not based on an existing one, simply omit the "based on X"
part. Thus, for example,
= (text as Inweb)
name: HTML
=
@ There are then a handful of other, optional, settings. The following are
all inherited automatically from the pattern we are based on, unless we
set them ourselves.
= (text as Inweb)
format: F
=
sets the format. At present, this must be |HTML|, |plain| (plain text),
|ePub|, |TeX|, |DVI|, or |PDF|.
= (text as Inweb)
number sections: yes
number sections: no
=
causes the weaver to apply numbers to section headings: the first included will
be number 1, and so on. Default is |no|.
= (text as Inweb)
embed CSS: yes
embed CSS: no
=
causes the weaver to embed copies of CSS files into each HTML file it creates,
rather than to link to them. Default is |no|, and there's no effect on non-HTML
formats.
= (text as Inweb)
default range: R
=
tells the weaver to assume the range |R|, if the user tries to weave a
multi-section web with this pattern. (For example, the standard HTML pattern
sets this to |sections|, causing a swarm of individual HTML files to be produced.)
Lastly, there are commands to do with plugins, covered below, which are also
inherited.
@ And there are a few settings which are not inherited: they apply only to the
pattern being defined, not to other patterns based on it.
= (text as Inweb)
tex command: C
=
tells the weaver that the TeX typesetting system should be invoked with the
shell command |C|. Default is |tex|. Similarly for |pdftex command: C|, used
when we want to make a PDF rather than a DVI.
= (text as Inweb)
open command: C
=
tells the weaver to use the shell command |C| if it wants to open the woven
file (i.e., on the user's computer) after it finishes. Default is |open|,
which works nicely for MacOS.
= (text as Inweb)
bibliographic data: K = V
=
tells the weaver to override the bibliographic data on any web it weaves, setting
the key |K| to the value |V|. For example:
= (text as Inweb)
bibliographic data: Booklet Title = A formal grammar for Inform 7
=
@h Plugins.
Plugins are named bundles of resources which are sometimes added to a weave,
and sometimes not, depending on its needs; they are placed in the pattern's
folder, and Inweb has access to the plugins not only for the current pattern,
but also for any pattern(s) it is based on. Plugins were designed for HTML,
but there's no reason they shouldn't also be useful for other formats.
A plugin is identified by name alone, case-insensitively, and that name should
be a single alphanumeric word. For example, the HTML pattern file says
= (text as Inweb)
plugin: Base
=
and this ensures that every file woven by this pattern, or any pattern based
on it, will use |Base|. There can be multiple such commands, for multiple such
plugins, and the ability isn't restricted to HTML alone.
In addition, the HTML format:
(a) includes |MathJax3| if the woven file needs mathematics notation;
(b) includes |Breadcrumbs| if it has a breadcrumb navigation trail;
(c) includes |Carousel| if it has any image carousels;
(d) includes |Popups| if it has any clickable popups (for example, to show
function usage);
(e) includes |Bigfoot| if it includes footnotes.
Two of these draw on other open-source projects:
(a) |MathJax3| is an excellent rendering system for mathematics on the web: see
https://docs.mathjax.org/en/latest/index.html
(b) |Bigfoot| is adapted from a popularly used piece of web coding: see
https://github.com/lemonmade/bigfoot
But if you would like your pattern to use different plugins to handle
mathematics and footnoting, provide lines like these in your pattern file,
but with your preferred plugin names:
= (text as Inweb)
mathematics plugin: MathJax3
footnotes plugin: Bigfoot
=
|Bigfoot| may eventually need to be simplified and rewritten: its big feet
presently tread on the |MathJax3| plugin, so right now it's not possible to
have mathematics in a footnote when |Bigfoot| is in use.
@ It's also possible to supply your own version of any plugin you would like
to tinker with. If you want |Carousel| to have rather different CSS effects,
for example, make your own copy of |Carousel| (copying it from the one in
the Inweb distribution at |inweb/Patterns/HTML/Carousel|) and place it in your
own pattern. Your version will prevail over the built-in one.
@ So what's in a plugin? There's not much to it. Every file in a plugin, whose
name does not begin with a |.|, is copied into the weave: that means it either
gets copied to the weave destination directory, or possibly to the |assets|
directory specified in the colony file (if there is one). However:
(a) If the format is HTML, and the filename ends |.css|, then a link to the
CSS file is automatically included in the head of the file. If the pattern
says to |embed CSS| (see above), then the file is spliced in rather than
being copied.
(b) If the format is HTML, and the filename ends |.js|, then a link to the
Javascript file is automatically included in the head of the file.
For example, the |Breadcrumbs| plugin contains an image file and a CSS file;
both are copied across, but a link to the CSS file is also included in the
woven file needing to use the plugin.
@h Embeddings.
Patterns with the HTML format may also want to provide "embeddings". These
are for embedded video/audio or other gadgets, and each different "service" --
|YouTube|, |SoundCloud|, and such -- is represented by an embedding file.
Inweb looks for these in the pattern's |Embedding| subdirectory, if there is
one; then it tries in the pattern we are based on, and so on until it gives
up and throws an error.
The services in the standard Inweb installation, then, are in
|inweb/Patterns/HTML/Embeddings|. It's easy to add new ones; for example,
by creating a similar fragment in |Tapestry/Embedding/WebTubeo.html| you
would provide for embedding videos from |WebTubeo| when using your pattern.
@h Syntax colouring.
No two people ever agree on the ideal colour scheme for syntax-colouring,
so one prime reason to create a custom pattern is to change Inweb's defaults.
Suppose Inweb wants to weave an extract of code written in, say, C. It will
use the programming language definition for C to make a syntax-colouring,
but then use the weave pattern to decide the colour scheme. For example,
it's up to the C language to say which text is a function name: but it's up
to the pattern to say whether functions are red or green.
A pattern based on HTML may provide a subdirectory called |Colouring|. If it
does, then the contents will be CSS files which provide colour schemes for
different programming languages. The scheme |Colours.css| is the fallback,
and is used for any language not providing a colour scheme; otherwise, a
language called, say, |Anaconda| would be coloured by |Anaconda-Colours.css|.
Inweb looks first in the |Colouring| directory of the current pattern, then
tries the pattern it is based on, and so on.
The practical effect is that if you want a pattern to colour Anaconda programs
in your own preferred way -- let's call this hypothetical pattern |SnakeSkin| --
then you need only write two files: |SnakeSkin/pattern.txt|, consisting of
the single line
= (text as Inweb)
name: SnakeSkin based on HTML
=
(or perhaps based on |GitHubPages|, if you want to host there); and then
a colouring file in |SnakeSkin/Colouring/Anaconda-Colours.css|. You should
make this by copying the default |Colours.css| and tinkering.
@ Note that Inweb supports multiple languages in the same weave, each having
their own colour schemes. To do this, it renames CSS spans on the fly in
order to prevent namespace clashes. But you can forget this, because it's
automatic.
@h Templates.
The final possible ingredient for a pattern is a "template"; this is a file
like a pro-forma letter, into which just the details need to be entered.
At present, Inweb does this in four circumstances:
(a) After a weave which ranges over more than a single section -- for example,
if it's a weave of a chapter, or of the complete web -- Inweb can generate
an "index". (This is more often a contents page, but Inweb uses the generic
term "index".) For this, it uses |unchaptered-index.html| if the web has
sections but no chapters; or |chaptered-index.html| if it has chapters. If
Inweb can't locate either of those, it looks simply for |index.html|, and
if it can't find that either then it gives up.
(b) Similarly, after a weave which is not a single section, Inweb looks to
see if there is |cover-sheet.XXX| template, in whatever format is being used:
|cover-sheet.tex|, or |cover-sheet.html|, as appropriate. This is placed at
the start of the material, and can be, e.g., a fancily typeset title page:
it's a feature intended more for serial formats than for the web.
(c) A weave using the HTML format is built around a pro-forma |template.html|.
This is required to exist and defines the overall shape of the HTML pages
which Inweb weaves.
(d) When one template wants to use another one -- i.e., as a consequence of
reasons (a) or (b).
As with other pattern-related resources, when Inweb needs to find, say,
|template.html|, it looks first in the current pattern's directory, then
tries the pattern this is based on, and so on. You can therefore override
the standard HTML pattern's |template.html| by placing your own in your
new pattern.
@ For example, here is a template file for making an HTML page:
= (text as Inweb)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>[[Booklet Title]]</title>
[[Plugins]]
</head>
<body>
[[Code]]
</body>
</html>
=
The weaver uses this to generate any HTML page of program taken from the
web being woven. (I.e., it doesn't use it to generate the index: only to
generate the pages for sections or chapters.) What you see is what you get,
except for the placeholders in double square brackets:
(a) |[[Code]]| expands to the body of the web page -- the headings,
paragraphs and so on.
(b) |[[Plugins]]| expands to any links to CSS or Javascript files needed
by the plugins being used -- see above.
(c) Any bibliographic datum for the web expands to its value: thus |[[Title]]|,
|[[Author]]| and so on. Booklet Title is one of these, but the weaver always
sets it to a sensible title for the current file being woven -- typically the
name of a section or chapter, if that's what the file will contain. Another
sometimes useful case to know is |[[Capitalized Title]]|, which is the title
in BLOCK CAPITAL LETTERS.
@ Other placeholders, not used in the example above, include:
(a) |[[Template X]]| expands to an insertion of the template file |X|.
(b) |[[Navigation]]| expands to the navigation sidebar in use when weaving
a colony of webs -- see //Making Weaves into Websites// for more, and for
syntaxes to do with links and URLs.
(c) |[[Breadcrumbs]]| expands to the HTML for the breadcrumb trail.
@h Indexing.
Some weaves are accompanied by indexes. For example, a standard weave into
sections (for the HTML pattern) generates an |index.html| contents page,
linking to the weaves for the individual sections. How is this done?
As noted above, some weaves are accompanied by indexes. For example, a
standard weave into sections (for the HTML pattern) generates an |index.html|
contents page, linking to the weaves for the individual sections. How is this
done?
Inweb looks in the pattern for a template file called either
|chaptered-index.html| or |unchaptered-index.html|, according to whether the
@ -131,16 +307,9 @@ web's sections are in chapters or simply in a single directory of |Sections|.
If it doesn't find this, it looks for a template simply called |index.html|,
using that template in either case.
An index is then made by taking this template file and running it through
the "template interpreter". This is basically a filter: that is, it
works through one line at a time, and most of the time it simply copies
the input to the output. The filtering consists of making the following
replacements. Any text in the form |[[...]]| is substituted with the
value |...|, which can be any of:
Now, however, there are additional double-squared placeholders available:
(a) A bibliographic variable, set at the top of the |Contents.w| section.
(b) One of the following details about the entire-web PDF (see below):
(a) One of the following details about the entire-web PDF (see below):
= (text as Inweb)
[[Complete Leafname]] [[Complete Extent]] [[Complete PDF Size]]
=
@ -164,9 +333,9 @@ substitution is the leafname of the original |.w| file. The Mean is the
average number of lines per paragraph: where this is large, the section
is rather raw and literate programming is not being used to the full.
@ But the template interpreter isn't merely "editing the stream", because
it can also handle repetitions. The following commands must occupy entire
lines:
@ And here the indexer isn't merely "editing the stream" of the template,
because it can also handle repetitions. The following commands must occupy
entire lines:
|[[Repeat Chapter]]| and |[[Repeat Section]]| begin blocks of lines which
are repeated for each chapter or section: the material to be repeated

46
Manual/How to Write a Web.w
View file

@ -571,13 +571,6 @@ With results like so:
The latter sets just the height (of the displayed waveform, that is --
arguably music has width and not height, but SoundCloud thinks otherwise).
@ It's easy to add services. These are all handled by using prototype code
for a suitable HTML |<iframe>|, and those prototypes are stored in the
|Embedding| subdirectory of the Inweb installation. But you can use your
own prototypes instead, by creating an |Embedding| subdirectory of your own
web; this overrides the ones built in. If your service is, say, |WebTubeo|,
then the file would be |W/Embedding/WebTubeo.html|.
@h Mathematics notation.
Literate programming is a good technique to justify code which hangs on
unobvious pieces of mathematics or computer science, and which must therefore
@ -601,27 +594,15 @@ That passage was achieved by typing this as the Inweb source:
which involves evaluating Euler's constant $\gamma$ and the first derivative
of the Riemann zeta function $\zeta'(z)$ at $z=2$.
=
Mathematical formulae can be typed in TeX notation between dollar signs,
as usual for TeX formulae.
The rendering is done by default via the MathJax3 project, full details
of which can be found at: https://docs.mathjax.org/en/latest/index.html
Inweb in fact managed this by including a "plugin" with the HTML page you
are now reading: a plugin called |MathJax3|. Plugins are simply small
fragments of HTML added to the head of a page, and usually contain Javascript
code needed for special effects in it. To use a different renderer, simply
change the value of |TeX Mathematics Plugin| for your web (by default it is
set to |MathJax3|); or if you don't want to use Javascript at all, change
this to |None|, but then Inweb can really only make the grossest approximation
of what you would like to achieve.
In some webs, TeX notation is an unwanted nuisance. So this feature can be
deactivated entirely by writing the following in the Contents section of a web:
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:
= (text as Inweb)
TeX Mathematics Notation: Off
TeX Mathematics Notation: $
TeX Mathematics Displayed Notation: $$
=
(This is always |On|, the default, or |Off|.)
Changing these to |None| causes Inweb to disregard mathematics entirely, and
treat it as any other text would be treated.
@h Footnotes.
Not everyone likes footnotes,[1] but sometimes they're a tidy way to make
@ -650,18 +631,7 @@ 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.
These blob-footnotes are fine for snarky asides or quick references, but long
discursive notes need more space, so if you intend to use those then you
should probably turn this rendering off altogether:
= (text as Inweb)
Footnotes Plugin: None
=
Footnotes are otherwise rendered by the |Bigfoot| plugin, which is the default
value of this; its big feet unfortunately tread on the |MathJax3| plugin, so
right now it's not possible to have mathematics in a footnote when |Bigfoot|
is in use.
@ Once again, notation may be an issue, and so it's controllable. By default,
Once again, notation may be an issue, and so it's controllable. By default,
we have:
= (text as Inweb)
Footnote Begins Notation: [

15
Manual/Making Weaves into Websites.w
View file

@ -96,6 +96,18 @@ directory name.) The point of this web is that it weaves to the |index.html|
home page; it's referred to in links as being the "overview", because that's
its name as a web.
@ The command |assets X| tells Inweb to place "assets" such as images, CSS and
JavaScript files which are needed by plugins (see //Advanced Weaving with Patterns//)
into the directory |X|. In practice, this avoids a great deal of duplication:
if there are 30 webs in the colony, there's no need for each to have its own
copy of the same CSS files for the basic page makeup. (But that is what will
indeed happen if the |assets| command is not used.)
Another convenience is |patterns X|, which tells X that some unusual weave
patterns can be found in directory |X|. That's useful if multiple webs in
the colony need to use the same pattern, and the pattern isn't one which is
built in the Inweb.
@h The navigation sidebar.
When assembling large numbers of woven websites together, as is needed for
example by the main Inform repository's GitHub pages, we need to navigate
@ -172,3 +184,6 @@ The links after the colon can also be Inweb cross-references, so, for example,
breadcrumbs: "Overview: //overview//"
=
makes a link to the web/module called |overview| in the colony file.
@h Adding custom HTML, CSS and such.
This is done by creating a new pattern: see //Advanced Weaving with Patterns//.

3
Patterns/Ebook/pattern.txt
View file

@ -1 +1,2 @@
format = ePub
name: Ebook
format: ePub

10
Patterns/GitHubPages/pattern.txt
View file

@ -1,5 +1,5 @@
from HTML
format = HTML
default-range = sections
plugin GitHub
plugin Breadcrumbs
name: GitHubPages based on HTML
format: HTML
default range: sections
plugin: GitHub
plugin: Breadcrumbs

9
Patterns/HTML/pattern.txt
View file

@ -1,3 +1,6 @@
format = HTML
default-range = sections
plugin Base
name: HTML
format: HTML
default range: sections
plugin: Base
mathematics plugin: MathJax3
footnotes plugin: Bigfoot

7
Patterns/InwebManualHTML/pattern.txt
View file

@ -1,7 +0,0 @@
from HTML
format = HTML
abbrevs = no
numbered = yes
Booklet Title = A modern system for literate programming
Author = User Guide
embed css

6
Patterns/InwebManualPDF/contents.tex
View file

@ -1,6 +0,0 @@
[[Repeat Section]]
\noindent{{\ssstitlefont [[Section Title]] -- [[Section Purpose]]}}
\vskip 0.1in
[[End Repeat]]
% It's very important that we do not \end.

3
Patterns/InwebManualPDF/cover-sheet.tex
View file

@ -1,3 +0,0 @@
[[Cover Sheet]]
% It's very important that we do not \end.

7
Patterns/InwebManualPDF/pattern.txt
View file

@ -1,7 +0,0 @@
from TeX
format = PDF
abbrevs = no
numbered = yes
Booklet Title = A modern system for literate programming
Author = User Guide
embed css

4
Patterns/PDF/pattern.txt
View file

@ -1,2 +1,2 @@
format = PDF
embed css
name: PDF
format: PDF

2
Patterns/Plain/pattern.txt Normal file
View file

@ -0,0 +1,2 @@
name: Plain
format: plain

4
Patterns/TestingInweb/pattern.txt
View file

@ -1,2 +1,2 @@
format = Debugging
default-range = sections
name: TestingInweb
format: Debugging

5
Preliminaries/How This Program Works.w
View file

@ -208,10 +208,7 @@ of Suzanne Vega's "Freeze Tag".
It then either calls //Swarm::weave_subset// -- meaning, a subset of the
web, going into a single output file -- or //Swarm::weave//, which it turn
splits the web into subsets and sends each of those to //Swarm::weave_subset//;
and it ensures that //Patterns::copy_payloads_into_weave// is called at the
end of the process. "Payloads" are files copied into the weave: for example,
an icon or a CSS file used in the website being constructed is a "payload".
splits the web into subsets and sends each of those to //Swarm::weave_subset//.
//Swarm::weave// also causes an "index" to be made, though "index" here is
Inweb jargon for something which is more likely a contents page listing the

1665
Tangled/inweb.c
View file

File diff suppressed because it is too large Load diff

16
docs/eastertide/S-rtd.html
View file

@ -59,7 +59,7 @@ fancy way, just to give the tires a kick.
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">PROGRAM_NAME</span><span class="plain-syntax"> </span><span class="string-syntax">"eastertide"</span>
</pre>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The <code class="display"><span class="extract-syntax">main</span></code> routine must start and end Foundation, and is not allowed to
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The <span class="extract"><span class="extract-syntax">main</span></span> routine must start and end Foundation, and is not allowed to
do much after that; but it is allowed to ask if error messages were generated,
so that it can return conventional Unix return values 0 (okay) or 1 (not okay).
</p>
@ -77,7 +77,7 @@ so that it can return conventional Unix return values 0 (okay) or 1 (not okay).
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b>The general scheme here is that we read the command line to work out which
the user is interested in, and store those in memory; but eventually we will
actually report on them, thus. <code class="display"><span class="extract-syntax">STDOUT</span></code> is the "text stream" for standard
actually report on them, thus. <span class="extract"><span class="extract-syntax">STDOUT</span></span> is the "text stream" for standard
output, i.e., writing to it will print to the Terminal or similar console.
</p>
@ -90,7 +90,7 @@ output, i.e., writing to it will print to the Terminal or similar console.
<span class="plain-syntax"> </span><a href="S-rtd.html#SP9" class="function-link"><span class="function-syntax">Main::report_on_years</span></a><span class="plain-syntax">(</span><span class="constant-syntax">STDOUT</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="S-rtd.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_2"></a><b>&#167;2.2. </b>All this program does is to print the date of Easter on any years requested,
but we'll give it some command-line options anyway. Foundation will add also
<code class="display"><span class="extract-syntax">-help</span></code> and a few others to the mix.
<span class="extract"><span class="extract-syntax">-help</span></span> and a few others to the mix.
</p>
@ -155,15 +155,15 @@ but we'll give it some command-line options anyway. Foundation will add also
<span class="ConsoleText-plain-syntax"> 15/4/1770</span>
<span class="ConsoleText-plain-syntax"> 15/4/1827</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>So let's get back to how this is done. The Foundation function <a href="../foundation-module/3-cla.html#SP8" class="internal">CommandLine::read</a>
calls our function <code class="display"><span class="ConsoleText-extract-syntax">Main::switch</span></code> when any of our three switches is used
calls our function <span class="extract"><span class="ConsoleText-extract-syntax">Main::switch</span></span> when any of our three switches is used
(we don't need to handle the ones Foundation added, only our own); and
<code class="display"><span class="ConsoleText-extract-syntax">Main::bareword</span></code> for any other words given on the command line. For example,
<span class="extract"><span class="ConsoleText-extract-syntax">Main::bareword</span></span> for any other words given on the command line. For example,
</p>
<pre class="ConsoleText-displayed-code all-displayed-code">
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">eastertide</span><span class="ConsoleText-identifier-syntax"> -american -calendar-file</span><span class="ConsoleText-plain-syntax"> cal.txt 1982 2007</span>
</pre>
<p class="inwebparagraph">...results in two calls to <code class="display"><span class="ConsoleText-extract-syntax">Main::switch</span></code>, then two to <code class="display"><span class="ConsoleText-extract-syntax">Main::bareword</span></code>.
<p class="inwebparagraph">...results in two calls to <span class="extract"><span class="ConsoleText-extract-syntax">Main::switch</span></span>, then two to <span class="extract"><span class="ConsoleText-extract-syntax">Main::bareword</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -196,7 +196,7 @@ calls our function <code class="display"><span class="ConsoleText-extract-syntax
</pre><ul class="endnotetexts"><li>This code is used in <a href="S-rtd.html#SP4">&#167;4</a>.</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>To make this a little more gratuitous, we'll give calendar files some
syntax. The following function is called on each line in turn; we're going
to trim white space, ignore blank lines, and also ignore any line beginning
withn a <code class="display"><span class="extract-syntax">#</span></code> as being a comment.
withn a <span class="extract"><span class="extract-syntax">#</span></span> as being a comment.
</p>
<pre class="displayed-code all-displayed-code">
@ -207,7 +207,7 @@ withn a <code class="display"><span class="extract-syntax">#</span></code> as be
<span class="plain-syntax"> </span><a href="S-rtd.html#SP6" class="function-link"><span class="function-syntax">Main::request</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>And with that done, we can process a request for a year, which comes from
either the command lihe (in which case <code class="display"><span class="extract-syntax">tfp</span></code> here is null), or from the
either the command lihe (in which case <span class="extract"><span class="extract-syntax">tfp</span></span> here is null), or from the
calendar file (in which case it remembers the filename and line number).
</p>

42
docs/foundation-module/1-fm.html
View file

@ -61,16 +61,16 @@ need to write a command-line utility in ANSI C with no dependencies on
other tools or libraries to speak of, you could do worse.
</p>
<p class="inwebparagraph">To use <code class="display"><span class="extract-syntax">foundation</span></code>, the Contents section of a web should include:
<p class="inwebparagraph">To use <span class="extract"><span class="extract-syntax">foundation</span></span>, the Contents section of a web should include:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> Import: foundation</span>
</pre>
<p class="inwebparagraph">before beginning the chapter rundown. There are then a few conventions
which must be followed. The <code class="display"><span class="extract-syntax">main</span></code> routine for the client should, as one
of its very first acts, call <code class="display"><span class="extract-syntax">Foundation::start()</span></code>, and should similarly, just
before it exits, call <code class="display"><span class="extract-syntax">Foundation::end()</span></code>. Any other module used should be
which must be followed. The <span class="extract"><span class="extract-syntax">main</span></span> routine for the client should, as one
of its very first acts, call <span class="extract"><span class="extract-syntax">Foundation::start()</span></span>, and should similarly, just
before it exits, call <span class="extract"><span class="extract-syntax">Foundation::end()</span></span>. Any other module used should be
started after Foundation starts, and ended before Foundation ends.
</p>
@ -97,7 +97,7 @@ supplied instead for that case.
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">DL</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment"> Current destination of debugging text: kept </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> until opened</span>
<span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">DL</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment"> Current destination of debugging text: kept </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> until opened</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>We'll use three truth states, the third of which can also mean "unknown".
</p>
@ -107,7 +107,7 @@ supplied instead for that case.
<span class="definition-keyword">define</span> <span class="constant-syntax">FALSE</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">NOT_APPLICABLE</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span>
</pre>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>And we recognise two different encodings for narrow (i.e., <code class="display"><span class="extract-syntax">char *</span></code>) C strings.
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>And we recognise two different encodings for narrow (i.e., <span class="extract"><span class="extract-syntax">char *</span></span>) C strings.
</p>
@ -117,12 +117,12 @@ supplied instead for that case.
</pre>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>It is assumed that our host filing system can manage at least 30-character
filenames, that space is legal as a character in a filename, and that trailing
extensions can be longer than 3 characters (in particular, that <code class="display"><span class="extract-syntax">.html</span></code> is
allowed). There are no clear rules but on Windows <code class="display"><span class="extract-syntax">MAX_PATH</span></code> can be as low as
extensions can be longer than 3 characters (in particular, that <span class="extract"><span class="extract-syntax">.html</span></span> is
allowed). There are no clear rules but on Windows <span class="extract"><span class="extract-syntax">MAX_PATH</span></span> can be as low as
260, and on Mac OS X the equivalent limit is 1024; both systems can house
files buried more deeply, but in both cases the user interface to the
operating system fails to recognise them. Some Linux implementations raise the
equivalent <code class="display"><span class="extract-syntax">PATH_MAX</span></code> limit as high as 4096. This seems a reasonable
equivalent <span class="extract"><span class="extract-syntax">PATH_MAX</span></span> limit as high as 4096. This seems a reasonable
compromise in practice:
</p>
@ -139,8 +139,8 @@ compromise in practice:
shutting down.
</p>
<p class="inwebparagraph">The Inweb notation <code class="display"><span class="extract-syntax">[[textliterals]]</span></code> inserts declarations of I-literals,
that is, literal <code class="display"><span class="extract-syntax">text_stream *</span></code> values written as <code class="display"><span class="extract-syntax">I"strings"</span></code>.
<p class="inwebparagraph">The Inweb notation <span class="extract"><span class="extract-syntax">[[textliterals]]</span></span> inserts declarations of I-literals,
that is, literal <span class="extract"><span class="extract-syntax">text_stream *</span></span> values written as <span class="extract"><span class="extract-syntax">I"strings"</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -154,10 +154,10 @@ that is, literal <code class="display"><span class="extract-syntax">text_stream
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Register the default debugging log writers</span> <span class="named-paragraph-number">8.3</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Register the default command line switches</span> <span class="named-paragraph-number">8.5</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8_1"></a><b>&#167;8.1. </b>After calling <code class="display"><span class="extract-syntax">Foundation::start()</span></code>, the client can register further stream
</pre><p class="inwebparagraph"><a id="SP8_1"></a><b>&#167;8.1. </b>After calling <span class="extract"><span class="extract-syntax">Foundation::start()</span></span>, the client can register further stream
writing routines, following these models: they define the meaning of escape
characters in <code class="display"><span class="extract-syntax">WRITE</span></code>, our version of formatted printing. <code class="display"><span class="extract-syntax">%f</span></code>, for example,
prints a filename by calling <code class="display"><span class="extract-syntax">Filenames::writer</span></code>.
characters in <span class="extract"><span class="extract-syntax">WRITE</span></span>, our version of formatted printing. <span class="extract"><span class="extract-syntax">%f</span></span>, for example,
prints a filename by calling <span class="extract"><span class="extract-syntax">Filenames::writer</span></span>.
</p>
@ -186,9 +186,9 @@ The following are always provided, but are all off by default.
<span class="plain-syntax"> </span><a href="2-dl.html#SP4" class="function-link"><span class="function-syntax">Log::declare_aspect</span></a><span class="plain-syntax">(</span><span class="constant-syntax">SHELL_USAGE_DA</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"shell usage"</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-dl.html#SP4" class="function-link"><span class="function-syntax">Log::declare_aspect</span></a><span class="plain-syntax">(</span><span class="constant-syntax">MEMORY_USAGE_DA</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"memory usage"</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-dl.html#SP4" class="function-link"><span class="function-syntax">Log::declare_aspect</span></a><span class="plain-syntax">(</span><span class="constant-syntax">TEXT_FILES_DA</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"text files"</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-fm.html#SP8">&#167;8</a>.</li></ul><p class="inwebparagraph"><a id="SP8_3"></a><b>&#167;8.3. </b>Debugging log writers are similar to stream writers, but implement the <code class="display"><span class="extract-syntax">$</span></code>
escapes only available to the debugging log. For example, <code class="display"><span class="extract-syntax">$S</span></code> calls the
<code class="display"><span class="extract-syntax">Streams::log</span></code> function to print a textual representation of the current
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-fm.html#SP8">&#167;8</a>.</li></ul><p class="inwebparagraph"><a id="SP8_3"></a><b>&#167;8.3. </b>Debugging log writers are similar to stream writers, but implement the <span class="extract"><span class="extract-syntax">$</span></span>
escapes only available to the debugging log. For example, <span class="extract"><span class="extract-syntax">$S</span></span> calls the
<span class="extract"><span class="extract-syntax">Streams::log</span></span> function to print a textual representation of the current
state of a stream.
</p>
@ -201,11 +201,11 @@ state of a stream.
<span class="plain-syntax"> </span><a href="2-wal.html#SP4" class="function-link"><span class="function-syntax">Writers::register_logger</span></a><span class="plain-syntax">(</span><span class="character-syntax">'a'</span><span class="plain-syntax">, &amp;</span><a href="4-taa.html#SP9" class="function-link"><span class="function-syntax">Tries::log_avinue</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-wal.html#SP4" class="function-link"><span class="function-syntax">Writers::register_logger</span></a><span class="plain-syntax">(</span><span class="character-syntax">'S'</span><span class="plain-syntax">, &amp;</span><a href="2-str.html#SP21" class="function-link"><span class="function-syntax">Streams::log</span></a><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-fm.html#SP8">&#167;8</a>.</li></ul><p class="inwebparagraph"><a id="SP8_4"></a><b>&#167;8.4. </b>We provide an optional service for parsing the command line. By default,
the <code class="display"><span class="extract-syntax">-log A</span></code> switch makes that aspect active, though it's hyphenated, so
for example <code class="display"><span class="extract-syntax">-log memory-usage</span></code> or <code class="display"><span class="extract-syntax">-log no-memory-usage</span></code>. <code class="display"><span class="extract-syntax">-fixtime</span></code> is
the <span class="extract"><span class="extract-syntax">-log A</span></span> switch makes that aspect active, though it's hyphenated, so
for example <span class="extract"><span class="extract-syntax">-log memory-usage</span></span> or <span class="extract"><span class="extract-syntax">-log no-memory-usage</span></span>. <span class="extract"><span class="extract-syntax">-fixtime</span></span> is
used to ease automated testing: we don't want to reject the output from
some tool just because it contains today's date and not the date when the
test was set up. <code class="display"><span class="extract-syntax">-crash</span></code> tells the tool to crash on a fatal error, rather
test was set up. <span class="extract"><span class="extract-syntax">-crash</span></span> tells the tool to crash on a fatal error, rather
than to exit cleanly, to make it easier to diagnose in a debugger.
</p>
@ -238,7 +238,7 @@ than to exit cleanly, to make it easier to diagnose in a debugger.
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"specify that this tool is installed at X"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-cla.html#SP5" class="function-link"><span class="function-syntax">CommandLine::end_group</span></a><span class="plain-syntax">();</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-fm.html#SP8">&#167;8</a>.</li></ul><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Once the following has been called, it is not safe to use any of the
<code class="display"><span class="extract-syntax">foundation</span></code> facilities. It should be called on any normal exit, but not on
<span class="extract"><span class="extract-syntax">foundation</span></span> facilities. It should be called on any normal exit, but not on
an early termination due to a fatal error, as this may lead to thread
safety problems.
</p>

40
docs/foundation-module/1-pp.html
View file

@ -58,7 +58,7 @@ two groups: the POSIX group, and Windows.
</p>
<p class="inwebparagraph">This Foundation module therefore comes with two variant versions of the
<code class="display"><span class="extract-syntax">Platform::</span></code> section of code. The one you're reading compiles on a POSIX
<span class="extract"><span class="extract-syntax">Platform::</span></span> section of code. The one you're reading compiles on a POSIX
operating system, and the other one on Windows.
</p>
@ -142,10 +142,10 @@ here is UTF-8 since OS X and Linux both adopt this.
<span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><a href="1-wp.html#SP4" class="function-link"><span class="function-syntax">Platform::getenv</span></a><span class="plain-syntax">(</span><span class="reserved-syntax">const</span><span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">getenv</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_POSIX is defined.</li><li>The function Platform::getenv is used in Windows Platform (<a href="1-wp.html#SP4">&#167;4</a>), Pathnames (<a href="3-pth.html#SP2">&#167;2</a>, <a href="3-pth.html#SP3">&#167;3</a>).</li></ul><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Executable location. </b>Fill the wide-char buffer <code class="display"><span class="extract-syntax">p</span></code> with the path to the current executable, up to
length <code class="display"><span class="extract-syntax">length</span></code>. This function is guaranteed to be called from only one
thread. Should the information be unavailable, or fail to fit into <code class="display"><span class="extract-syntax">p</span></code>,
truncate <code class="display"><span class="extract-syntax">p</span></code> to zero length. (On some platforms, the information will
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_POSIX is defined.</li><li>The function Platform::getenv is used in Windows Platform (<a href="1-wp.html#SP4">&#167;4</a>), Pathnames (<a href="3-pth.html#SP2">&#167;2</a>, <a href="3-pth.html#SP3">&#167;3</a>).</li></ul><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Executable location. </b>Fill the wide-char buffer <span class="extract"><span class="extract-syntax">p</span></span> with the path to the current executable, up to
length <span class="extract"><span class="extract-syntax">length</span></span>. This function is guaranteed to be called from only one
thread. Should the information be unavailable, or fail to fit into <span class="extract"><span class="extract-syntax">p</span></span>,
truncate <span class="extract"><span class="extract-syntax">p</span></span> to zero length. (On some platforms, the information will
always be unavailable: that doesn't mean we can't run on those platforms,
just that installation and use of Foundation-built tools is less convenient.)
</p>
@ -156,10 +156,10 @@ just that installation and use of Foundation-built tools is less convenient.)
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Follow the proc filesystem symlink to the real filesystem's file</span> <span class="named-paragraph-number">9.1</span>&gt;<span class="character-syntax">;</span>
<span class="character-syntax"> </span>&lt;<span class="named-paragraph">Transcode buffer, which is locale-encoded, into the wide-char buffer</span> <span class="named-paragraph-number">9.2</span>&gt;<span class="character-syntax">;</span>
<span class="character-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_LINUX and PLATFORM_POSIX are defined.</li><li>The function Platform::where_am_i is used in <a href="1-pp.html#SP9_1_1">&#167;9.1.1</a>, <a href="1-pp.html#SP9_1_2">&#167;9.1.2</a>, <a href="1-pp.html#SP9_1_3">&#167;9.1.3</a>, Windows Platform (<a href="1-wp.html#SP5">&#167;5</a>), Pathnames (<a href="3-pth.html#SP3">&#167;3</a>).</li></ul><p class="inwebparagraph"><a id="SP9_1"></a><b>&#167;9.1. </b>On Linux, <code class="display"><span class="extract-syntax">/proc/self/exe</span></code> is a symlink to the current process's executable.
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_LINUX and PLATFORM_POSIX are defined.</li><li>The function Platform::where_am_i is used in <a href="1-pp.html#SP9_1_1">&#167;9.1.1</a>, <a href="1-pp.html#SP9_1_2">&#167;9.1.2</a>, <a href="1-pp.html#SP9_1_3">&#167;9.1.3</a>, Windows Platform (<a href="1-wp.html#SP5">&#167;5</a>), Pathnames (<a href="3-pth.html#SP3">&#167;3</a>).</li></ul><p class="inwebparagraph"><a id="SP9_1"></a><b>&#167;9.1. </b>On Linux, <span class="extract"><span class="extract-syntax">/proc/self/exe</span></span> is a symlink to the current process's executable.
Follow that link to find the path. Normally when reading a symlink, one uses
<code class="display"><span class="extract-syntax">lstat()</span></code> to find the path length instead of guessing <code class="display"><span class="extract-syntax">PATH_MAX</span></code>, but the
symlinks in <code class="display"><span class="extract-syntax">/proc</span></code> are special and don't provide a length to <code class="display"><span class="extract-syntax">lstat()</span></code>.
<span class="extract"><span class="extract-syntax">lstat()</span></span> to find the path length instead of guessing <span class="extract"><span class="extract-syntax">PATH_MAX</span></span>, but the
symlinks in <span class="extract"><span class="extract-syntax">/proc</span></span> are special and don't provide a length to <span class="extract"><span class="extract-syntax">lstat()</span></span>.
</p>
@ -240,24 +240,24 @@ string.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">system</span><span class="plain-syntax">(</span><span class="identifier-syntax">cmd</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_POSIX is defined and if PLATFORM_MACOS is undefined.</li><li>The function Platform::system is used in <a href="1-pp.html#SP11">&#167;11</a>, <a href="1-pp.html#SP14">&#167;14</a>, Windows Platform (<a href="1-wp.html#SP6">&#167;6</a>), Shell (<a href="3-shl.html#SP5">&#167;5</a>).</li></ul><p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>In MacOS 10.5, a new implementation of the C standard library
crippled performance of <code class="display"><span class="extract-syntax">system()</span></code> by placing it behind a global mutex, so
crippled performance of <span class="extract"><span class="extract-syntax">system()</span></span> by placing it behind a global mutex, so
that it was impossible for two cores to be calling the function at the same
time. The net effect of this is that the Inform test suite, executing in
Intest, ran in 1/16th speed. This issue didn't come to light until 2019,
however, because the build setting <code class="display"><span class="extract-syntax">-mmacosx-version-min=10.4</span></code> turned out
to force use of the (perfectly good) pre-10.5 library, where <code class="display"><span class="extract-syntax">system()</span></code>
however, because the build setting <span class="extract"><span class="extract-syntax">-mmacosx-version-min=10.4</span></span> turned out
to force use of the (perfectly good) pre-10.5 library, where <span class="extract"><span class="extract-syntax">system()</span></span>
continued to run in a multi-threaded way, just as it does on Linux and
most all other Unixes. The old library was eventually withdrawn by Apple
in 2018, and in any case would stop working at some point in 2019-20 due
to the final removal of 32-bit binary support from MacOS.
</p>
<p class="inwebparagraph">It took several days to find a pthread-safe way to reimplement <code class="display"><span class="extract-syntax">system()</span></code>.
The obvious way, using <code class="display"><span class="extract-syntax">fork()</span></code> and then running <code class="display"><span class="extract-syntax">execve()</span></code> on the child
process &mdash; essentially the standard way to implement <code class="display"><span class="extract-syntax">system()</span></code>, if you forget
<p class="inwebparagraph">It took several days to find a pthread-safe way to reimplement <span class="extract"><span class="extract-syntax">system()</span></span>.
The obvious way, using <span class="extract"><span class="extract-syntax">fork()</span></span> and then running <span class="extract"><span class="extract-syntax">execve()</span></span> on the child
process &mdash; essentially the standard way to implement <span class="extract"><span class="extract-syntax">system()</span></span>, if you forget
about signal-handling &mdash; led to obscure and unrepeatable memory corruption
bugs in Intest, with the worker threads apparently writing on each other's
memory space. Using <code class="display"><span class="extract-syntax">posix_spawn()</span></code> instead appears to work better.
memory space. Using <span class="extract"><span class="extract-syntax">posix_spawn()</span></span> instead appears to work better.
</p>
<pre class="displayed-code all-displayed-code">
@ -314,7 +314,7 @@ memory space. Using <code class="display"><span class="extract-syntax">posix_spa
<span class="plain-syntax"> </span><span class="identifier-syntax">DIR</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dirp</span><span class="plain-syntax"> = (</span><span class="identifier-syntax">DIR</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">D</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">closedir</span><span class="plain-syntax">(</span><span class="identifier-syntax">dirp</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_POSIX is defined.</li><li>The function Platform::mkdir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Pathnames (<a href="3-pth.html#SP9">&#167;9</a>).</li><li>The function Platform::opendir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Directories (<a href="3-drc.html#SP2">&#167;2</a>).</li><li>The function Platform::readdir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Directories (<a href="3-drc.html#SP2">&#167;2</a>).</li><li>The function Platform::closedir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Directories (<a href="3-drc.html#SP2">&#167;2</a>).</li></ul><p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. Timestamp. </b>There are implementations of the C standard library where <code class="display"><span class="extract-syntax">time_t</span></code> has
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_POSIX is defined.</li><li>The function Platform::mkdir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Pathnames (<a href="3-pth.html#SP9">&#167;9</a>).</li><li>The function Platform::opendir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Directories (<a href="3-drc.html#SP2">&#167;2</a>).</li><li>The function Platform::readdir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Directories (<a href="3-drc.html#SP2">&#167;2</a>).</li><li>The function Platform::closedir is used in Windows Platform (<a href="1-wp.html#SP7">&#167;7</a>), Directories (<a href="3-drc.html#SP2">&#167;2</a>).</li></ul><p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. Timestamp. </b>There are implementations of the C standard library where <span class="extract"><span class="extract-syntax">time_t</span></span> has
super-weird behaviour, but on almost POSIX systems, time 0 corresponds to
midnight on 1 January 1970. All we really need is that the "never" value
is one which is earlier than any possible timestamp on the files we'll
@ -332,11 +332,11 @@ be dealing with.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-wp.html#SP12" class="function-link"><span class="function-syntax">Platform::never_time</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_POSIX is defined.</li><li>The function Platform::never_time is used in Windows Platform (<a href="1-wp.html#SP12">&#167;12</a>).</li><li>The function Platform::timestamp is used in Windows Platform (<a href="1-wp.html#SP12">&#167;12</a>), Filenames (<a href="3-fln.html#SP12">&#167;12</a>).</li></ul><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Sync. </b>Both names here are of directories which do exist. The function makes
the <code class="display"><span class="extract-syntax">dest</span></code> tree an exact copy of the <code class="display"><span class="extract-syntax">source</span></code> tree (and therefore deletes
anything different which was originally in <code class="display"><span class="extract-syntax">dest</span></code>).
the <span class="extract"><span class="extract-syntax">dest</span></span> tree an exact copy of the <span class="extract"><span class="extract-syntax">source</span></span> tree (and therefore deletes
anything different which was originally in <span class="extract"><span class="extract-syntax">dest</span></span>).
</p>
<p class="inwebparagraph">In POSIX world, we can fairly well depend on <code class="display"><span class="extract-syntax">rsync</span></code> being around:
<p class="inwebparagraph">In POSIX world, we can fairly well depend on <span class="extract"><span class="extract-syntax">rsync</span></span> being around:
</p>
<pre class="displayed-code all-displayed-code">
@ -374,7 +374,7 @@ SoundJam, the program which Apple bought and rebranded as iTunes. Apple now
seems to consider this alert a general-purpose "something good has happened".
</p>
<p class="inwebparagraph">It is anybody's guess how long Apple will permit the shell command <code class="display"><span class="extract-syntax">osascript</span></code>
<p class="inwebparagraph">It is anybody's guess how long Apple will permit the shell command <span class="extract"><span class="extract-syntax">osascript</span></span>
to survive, given the MacOS team's current hostility to scripting; we're
actually running a one-line AppleScript here.
</p>

36
docs/foundation-module/1-wp.html
View file

@ -47,7 +47,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="1-wp.html#SP2">&#167;2. Microsoft Windows</a></li><li><a href="1-wp.html#SP4">&#167;4. Environment variables</a></li><li><a href="1-wp.html#SP5">&#167;5. Executable location</a></li><li><a href="1-wp.html#SP6">&#167;6. Shell commands</a></li><li><a href="1-wp.html#SP7">&#167;7. Directory handling</a></li><li><a href="1-wp.html#SP8">&#167;8. Sleep</a></li><li><a href="1-wp.html#SP9">&#167;9. Notifications</a></li><li><a href="1-wp.html#SP10">&#167;10. Concurrency</a></li><li><a href="1-wp.html#SP12">&#167;12. Timestamp</a></li><li><a href="1-wp.html#SP13">&#167;13. Mutexes</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This Foundation module comes with two variant versions of the <code class="display"><span class="extract-syntax">Platform::</span></code>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This Foundation module comes with two variant versions of the <span class="extract"><span class="extract-syntax">Platform::</span></span>
section of code. The one you're reading compiles on Windows, and the other
on a POSIX operating system.
</p>
@ -70,21 +70,21 @@ on a POSIX operating system.
<span class="plain-syntax">#</span><span class="identifier-syntax">include</span><span class="plain-syntax"> &lt;</span><span class="identifier-syntax">errno</span><span class="plain-syntax">.</span><span class="identifier-syntax">h</span><span class="plain-syntax">&gt;</span>
<span class="plain-syntax">#</span><span class="identifier-syntax">include</span><span class="plain-syntax"> &lt;</span><span class="identifier-syntax">io</span><span class="plain-syntax">.</span><span class="identifier-syntax">h</span><span class="plain-syntax">&gt;</span>
<span class="plain-syntax">#</span><span class="identifier-syntax">include</span><span class="plain-syntax"> &lt;</span><span class="identifier-syntax">windows</span><span class="plain-syntax">.</span><span class="identifier-syntax">h</span><span class="plain-syntax">&gt;</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>A Windows-safe form of <code class="display"><span class="extract-syntax">isdigit</span></code>. Annoyingly, the C specification allows
the implementation to have <code class="display"><span class="extract-syntax">char</span></code> either signed or unsigned. On Windows it's
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>A Windows-safe form of <span class="extract"><span class="extract-syntax">isdigit</span></span>. Annoyingly, the C specification allows
the implementation to have <span class="extract"><span class="extract-syntax">char</span></span> either signed or unsigned. On Windows it's
generally signed. Now, consider what happens with a character value of
acute-e. This has an <code class="display"><span class="extract-syntax">unsigned char</span></code> value of 233. When stored in a <code class="display"><span class="extract-syntax">char</span></code>
on Windows, this becomes a value of <code class="display"><span class="extract-syntax">-23</span></code>. When this is passed to <code class="display"><span class="extract-syntax">isdigit()</span></code>,
we need to consider the prototype for <code class="display"><span class="extract-syntax">isdigit()</span></code>:
acute-e. This has an <span class="extract"><span class="extract-syntax">unsigned char</span></span> value of 233. When stored in a <span class="extract"><span class="extract-syntax">char</span></span>
on Windows, this becomes a value of <span class="extract"><span class="extract-syntax">-23</span></span>. When this is passed to <span class="extract"><span class="extract-syntax">isdigit()</span></span>,
we need to consider the prototype for <span class="extract"><span class="extract-syntax">isdigit()</span></span>:
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">int isdigit(int);</span></code>
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">int isdigit(int);</span></span>
</p>
<p class="inwebparagraph">So, when casting to int we get <code class="display"><span class="extract-syntax">-23</span></code>, not <code class="display"><span class="extract-syntax">233</span></code>. Unfortunately the return value
from <code class="display"><span class="extract-syntax">isdigit()</span></code> is only defined by the C specification for values in the
range 0 to 255 (and also EOF), so the return value for <code class="display"><span class="extract-syntax">-23</span></code> is undefined.
And with Windows GCC, <code class="display"><span class="extract-syntax">isdigit(-23)</span></code> returns a non-zero value.
<p class="inwebparagraph">So, when casting to int we get <span class="extract"><span class="extract-syntax">-23</span></span>, not <span class="extract"><span class="extract-syntax">233</span></span>. Unfortunately the return value
from <span class="extract"><span class="extract-syntax">isdigit()</span></span> is only defined by the C specification for values in the
range 0 to 255 (and also EOF), so the return value for <span class="extract"><span class="extract-syntax">-23</span></span> is undefined.
And with Windows GCC, <span class="extract"><span class="extract-syntax">isdigit(-23)</span></span> returns a non-zero value.
</p>
@ -112,10 +112,10 @@ And with Windows GCC, <code class="display"><span class="extract-syntax">isdigit
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">getenv</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Executable location. </b>Fill the wide-char buffer <code class="display"><span class="extract-syntax">p</span></code> with the path to the current executable, up to
length <code class="display"><span class="extract-syntax">length</span></code>. This function is guaranteed to be called from only one
thread. Should the information be unavailable, or fail to fit into <code class="display"><span class="extract-syntax">p</span></code>,
truncate <code class="display"><span class="extract-syntax">p</span></code> to zero length. (On some platforms, the information will
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Executable location. </b>Fill the wide-char buffer <span class="extract"><span class="extract-syntax">p</span></span> with the path to the current executable, up to
length <span class="extract"><span class="extract-syntax">length</span></span>. This function is guaranteed to be called from only one
thread. Should the information be unavailable, or fail to fit into <span class="extract"><span class="extract-syntax">p</span></span>,
truncate <span class="extract"><span class="extract-syntax">p</span></span> to zero length. (On some platforms, the information will
always be unavailable: that doesn't mean we can't run on those platforms,
just that installation and use of Foundation-built tools is less convenient.)
</p>
@ -205,8 +205,8 @@ just that installation and use of Foundation-built tools is less convenient.)
<span class="plain-syntax"> </span><span class="identifier-syntax">DIR</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dirp</span><span class="plain-syntax"> = (</span><span class="identifier-syntax">DIR</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">D</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">closedir</span><span class="plain-syntax">(</span><span class="identifier-syntax">dirp</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Sleep. </b>The Windows <code class="display"><span class="extract-syntax">Sleep</span></code> call measures time in milliseconds, whereas
POSIX <code class="display"><span class="extract-syntax">sleep</span></code> is for seconds.
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Sleep. </b>The Windows <span class="extract"><span class="extract-syntax">Sleep</span></span> call measures time in milliseconds, whereas
POSIX <span class="extract"><span class="extract-syntax">sleep</span></span> is for seconds.
</p>
<pre class="displayed-code all-displayed-code">
@ -266,7 +266,7 @@ POSIX <code class="display"><span class="extract-syntax">sleep</span></code> is
<span class="identifier-syntax">size_t</span><span class="plain-syntax"> </span><span class="function-syntax">Platform::get_thread_stack_size</span><button class="popup" onclick="togglePopup('usagePopup22')">...<span class="popuptext" id="usagePopup22">Usage of <b>Platform::get_thread_stack_size</b>:<br>POSIX Platforms - <a href="1-pp.html#SP19">&#167;19</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pthread_attr_t</span><span class="plain-syntax">* </span><span class="identifier-syntax">pa</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. Timestamp. </b>There are implementations of the C standard library where <code class="display"><span class="extract-syntax">time_t</span></code> has
</pre><ul class="endnotetexts"><li>This paragraph is used only if PLATFORM_WINDOWS is defined.</li></ul><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. Timestamp. </b>There are implementations of the C standard library where <span class="extract"><span class="extract-syntax">time_t</span></span> has
super-weird behaviour, but on almost POSIX systems, time 0 corresponds to
midnight on 1 January 1970. All we really need is that the "never" value
is one which is earlier than any possible timestamp on the files we'll

14
docs/foundation-module/2-dct.html
View file

@ -104,8 +104,8 @@ efficiency's sake the caller can set them up with an initial size of her choice.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Hashing. </b>The whole point of a hash table is that it crudely sorts the contents by a rough
indication of the key values. This crude indication is the hash value, calculated
here. If there are <code class="display"><span class="extract-syntax">N</span></code> slots in the dictionary table, this tells us which slot
(from 0 to <code class="display"><span class="extract-syntax">N-1</span></code>) a given key value belongs in.
here. If there are <span class="extract"><span class="extract-syntax">N</span></span> slots in the dictionary table, this tells us which slot
(from 0 to <span class="extract"><span class="extract-syntax">N-1</span></span>) a given key value belongs in.
</p>
<pre class="displayed-code all-displayed-code">
@ -132,8 +132,8 @@ so be careful if thread safety's an issue.
<span class="plain-syntax"> </span><a href="2-dct.html#SP7" class="function-link"><span class="function-syntax">Dictionaries::find_p</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">, </span><span class="identifier-syntax">K</span><span class="plain-syntax">, -1);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>A nuisance we have to live with is that we often want to express the key
as wide text (so that we can use literals like <code class="display"><span class="extract-syntax">L"my-key"</span></code>) instead of text
streams. So we also offer versions suffixed <code class="display"><span class="extract-syntax">_literal</span></code>:
as wide text (so that we can use literals like <span class="extract"><span class="extract-syntax">L"my-key"</span></span>) instead of text
streams. So we also offer versions suffixed <span class="extract"><span class="extract-syntax">_literal</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -157,8 +157,8 @@ streams. So we also offer versions suffixed <code class="display"><span class="e
<span class="plain-syntax"> </span><a href="2-dct.html#SP5" class="function-link"><span class="function-syntax">Dictionaries::destroy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">, </span><span class="identifier-syntax">K</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">K</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>So, then, find an entry (if <code class="display"><span class="extract-syntax">change</span></code> is <code class="display"><span class="extract-syntax">0</span></code>), create it (if <code class="display"><span class="extract-syntax">+1</span></code>) or delete
it (if <code class="display"><span class="extract-syntax">-1</span></code>).
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>So, then, find an entry (if <span class="extract"><span class="extract-syntax">change</span></span> is <span class="extract"><span class="extract-syntax">0</span></span>), create it (if <span class="extract"><span class="extract-syntax">+1</span></span>) or delete
it (if <span class="extract"><span class="extract-syntax">-1</span></span>).
</p>
<pre class="displayed-code all-displayed-code">
@ -312,7 +312,7 @@ so we provide convenient wrappers with the correct C types.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> (</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">value</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>We only need a read operation, because the caller can write to the dictionary
entry by reading the text pointer and then using <code class="display"><span class="extract-syntax">WRITE_TO</span></code>.
entry by reading the text pointer and then using <span class="extract"><span class="extract-syntax">WRITE_TO</span></span>.
</p>
<pre class="displayed-code all-displayed-code">

26
docs/foundation-module/2-dl.html
View file

@ -58,16 +58,16 @@ judiciously placed print statements" (Brian Kernighan).
</p>
<p class="inwebparagraph">To write to the debugging log, we must in principle write to a stream called
<code class="display"><span class="extract-syntax">DL</span></code>. In practice we more often use a pair of pseudo-functions called <code class="display"><span class="extract-syntax">LOG</span></code>
and <code class="display"><span class="extract-syntax">LOGIF</span></code>, which are macros defined in the section on Streams. For
<span class="extract"><span class="extract-syntax">DL</span></span>. In practice we more often use a pair of pseudo-functions called <span class="extract"><span class="extract-syntax">LOG</span></span>
and <span class="extract"><span class="extract-syntax">LOGIF</span></span>, which are macros defined in the section on Streams. For
instance, the pseudo-function-call
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> LOGIF(WHATEVER, "Heading %d skipped\n", n);</span>
</pre>
<p class="inwebparagraph">prints the line in question to the debugging log only if the aspect <code class="display"><span class="extract-syntax">WHATEVER</span></code>
is currently switched on. Plain <code class="display"><span class="extract-syntax">LOG</span></code> does the same, but unconditionally.
<p class="inwebparagraph">prints the line in question to the debugging log only if the aspect <span class="extract"><span class="extract-syntax">WHATEVER</span></span>
is currently switched on. Plain <span class="extract"><span class="extract-syntax">LOG</span></span> does the same, but unconditionally.
</p>
@ -96,8 +96,8 @@ length.
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">debugging_aspect</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure debugging_aspect is accessed in 8/bdfw and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>And now we must define all those constants and names. Note that the
<code class="display"><span class="extract-syntax">TRUE</span></code> or <code class="display"><span class="extract-syntax">FALSE</span></code> settings below are the defaults, and apply unless the
source says otherwise. The <code class="display"><span class="extract-syntax">alternate</span></code> settings are those used in
<span class="extract"><span class="extract-syntax">TRUE</span></span> or <span class="extract"><span class="extract-syntax">FALSE</span></span> settings below are the defaults, and apply unless the
source says otherwise. The <span class="extract"><span class="extract-syntax">alternate</span></span> settings are those used in
trace-sentences mode, that is, between asterisk sentences.
</p>
@ -155,11 +155,11 @@ behind the scenes; but such a log file is often buffered by the filing system,
so that a sudden crash of Inform may result in the loss of recent data written to
the log. Which is a pity, since this is exactly the most useful evidence as to
the cause of the crash in the first place. Accordingly, we fairly often
<code class="display"><span class="extract-syntax">fflush</span></code> the debug log file, forcing any buffered output to be written.
<span class="extract"><span class="extract-syntax">fflush</span></span> the debug log file, forcing any buffered output to be written.
</p>
<p class="inwebparagraph">In this rest of this section, we always assume that <code class="display"><span class="extract-syntax">DL</span></code> is open. Note that it
is possible this has been switched to be <code class="display"><span class="extract-syntax">stdout</span></code>, or even that it is
<p class="inwebparagraph">In this rest of this section, we always assume that <span class="extract"><span class="extract-syntax">DL</span></span> is open. Note that it
is possible this has been switched to be <span class="extract"><span class="extract-syntax">stdout</span></span>, or even that it is
temporarily the sentence tracing file: but we don't care.
</p>
@ -255,12 +255,12 @@ debug log, and is used when errors occur.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>We also want the ability to change debugging log settings from the command
line; the command line form is derived from the textual form by replacing
every space with a hyphen: for instance, <code class="display"><span class="extract-syntax">property-provision</span></code>.
every space with a hyphen: for instance, <span class="extract"><span class="extract-syntax">property-provision</span></span>.
</p>
<p class="inwebparagraph">We also recognise <code class="display"><span class="extract-syntax">no-property-provision</span></code> to switch this off again,
<code class="display"><span class="extract-syntax">everything</span></code> and <code class="display"><span class="extract-syntax">nothing</span></code> with the obvious meanings, and <code class="display"><span class="extract-syntax">list</span></code> to
print out a list of debugging aspects to <code class="display"><span class="extract-syntax">STDOUT</span></code>.
<p class="inwebparagraph">We also recognise <span class="extract"><span class="extract-syntax">no-property-provision</span></span> to switch this off again,
<span class="extract"><span class="extract-syntax">everything</span></span> and <span class="extract"><span class="extract-syntax">nothing</span></span> with the obvious meanings, and <span class="extract"><span class="extract-syntax">list</span></span> to
print out a list of debugging aspects to <span class="extract"><span class="extract-syntax">STDOUT</span></span>.
</p>
<pre class="displayed-code all-displayed-code">

18
docs/foundation-module/2-llas.html
View file

@ -172,10 +172,10 @@ want speed rather than memory efficiency.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="plain-syntax">?(</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">item_contents</span><span class="plain-syntax">):</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. A macro-ized API. </b>These intentionally hide the implementation. The difference between
<code class="display"><span class="extract-syntax">FIRST_IN_LINKED_LIST</span></code> and <code class="display"><span class="extract-syntax">FIRST_ITEM_IN_LINKED_LIST</span></code> is that one returns
<span class="extract"><span class="extract-syntax">FIRST_IN_LINKED_LIST</span></span> and <span class="extract"><span class="extract-syntax">FIRST_ITEM_IN_LINKED_LIST</span></span> is that one returns
the first structure in the list, and the other returns the first
<code class="display"><span class="extract-syntax">linked_list_item</span></code> chunk in the list. From the latter you can make the
former using <code class="display"><span class="extract-syntax">CONTENT_IN_ITEM</span></code>, but not vice versa. The same object
<span class="extract"><span class="extract-syntax">linked_list_item</span></span> chunk in the list. From the latter you can make the
former using <span class="extract"><span class="extract-syntax">CONTENT_IN_ITEM</span></span>, but not vice versa. The same object
may be listed in many different lists, so if all you have is the object,
you don't know its place in the list.
</p>
@ -203,14 +203,14 @@ you don't know its place in the list.
<span class="definition-keyword">define</span> <span class="identifier-syntax">LAST_IN_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> ((</span><span class="identifier-syntax">T</span><span class="plain-syntax"> *) (</span><a href="2-llas.html#SP6" class="function-link"><span class="function-syntax">LinkedLists::content</span></a><span class="plain-syntax">(</span><a href="2-llas.html#SP6" class="function-link"><span class="function-syntax">LinkedLists::last</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">L</span><span class="plain-syntax">))))</span>
</pre>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>The following macro requires slight care to use: the list <code class="display"><span class="extract-syntax">L</span></code> needs to be
calculable without side-effects. There's no such worry over <code class="display"><span class="extract-syntax">P</span></code> or <code class="display"><span class="extract-syntax">T</span></code>, since
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>The following macro requires slight care to use: the list <span class="extract"><span class="extract-syntax">L</span></span> needs to be
calculable without side-effects. There's no such worry over <span class="extract"><span class="extract-syntax">P</span></span> or <span class="extract"><span class="extract-syntax">T</span></span>, since
they're just identifier names: the loop variable and the type name respectively.
</p>
<p class="inwebparagraph">Note that the loop variable <code class="display"><span class="extract-syntax">P</span></code> must already be defined. Inside the loop body,
a new variable will also then exist, <code class="display"><span class="extract-syntax">P_item</span></code>, to refer to the item which
points to <code class="display"><span class="extract-syntax">P</span></code>. This allows us to iterate despite the comments above.
<p class="inwebparagraph">Note that the loop variable <span class="extract"><span class="extract-syntax">P</span></span> must already be defined. Inside the loop body,
a new variable will also then exist, <span class="extract"><span class="extract-syntax">P_item</span></span>, to refer to the item which
points to <span class="extract"><span class="extract-syntax">P</span></span>. This allows us to iterate despite the comments above.
</p>
@ -227,7 +227,7 @@ front iten.
</p>
<p class="inwebparagraph">We provide an abstract type name for these stacks, even though they're the
exact same structure. For reasons to do with the way <code class="display"><span class="extract-syntax">typedef</span></code> works in C,
exact same structure. For reasons to do with the way <span class="extract"><span class="extract-syntax">typedef</span></span> works in C,
it is awkward to typedef the two names together, so we'll simply use the
preprocessor:
</p>

134
docs/foundation-module/2-mmr.html
View file

@ -69,11 +69,11 @@ from 0. These IDs will be unique across all threads.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Before going much further, we will need to anticipate what the memory
manager wants. An "object" is a copy in memory of a C <code class="display"><span class="extract-syntax">struct</span></code>; thus,
a plain <code class="display"><span class="extract-syntax">int</span></code> is not an object. The memory manager can only deal with
a given type of <code class="display"><span class="extract-syntax">struct</span></code> if it contains three special elements, and we
manager wants. An "object" is a copy in memory of a C <span class="extract"><span class="extract-syntax">struct</span></span>; thus,
a plain <span class="extract"><span class="extract-syntax">int</span></span> is not an object. The memory manager can only deal with
a given type of <span class="extract"><span class="extract-syntax">struct</span></span> if it contains three special elements, and we
define those using a macro. Thus, if the user wants to allocate larger
structures of type <code class="display"><span class="extract-syntax">thingummy</span></code>, then it needs to be defined like so:
structures of type <span class="extract"><span class="extract-syntax">thingummy</span></span>, then it needs to be defined like so:
</p>
<pre class="displayed-code all-displayed-code">
@ -98,8 +98,8 @@ IDs; and they cannot be iterated over.
<span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prev_structure</span><span class="plain-syntax">; </span><span class="comment"> Previous object in double-linked list</span>
</pre>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>It is also necessary to define a constant in the following enumeration
family: for <code class="display"><span class="extract-syntax">thingummy</span></code>, it would be <code class="display"><span class="extract-syntax">thingummy_MT</span></code>. Had it been a smaller
object, it would have been <code class="display"><span class="extract-syntax">thingummy_array_MT</span></code> instead.
family: for <span class="extract"><span class="extract-syntax">thingummy</span></span>, it would be <span class="extract"><span class="extract-syntax">thingummy_MT</span></span>. Had it been a smaller
object, it would have been <span class="extract"><span class="extract-syntax">thingummy_array_MT</span></span> instead.
</p>
<p class="inwebparagraph">There is no significance to the order in which structures are registered
@ -147,9 +147,9 @@ with the memory system. The ones here are those needed by Foundation.
</pre>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>For each type of object to be allocated, a single structure of the
following design is maintained. Types which are allocated individually,
like world objects, have <code class="display"><span class="extract-syntax">no_allocated_together</span></code> set to 1, and the doubly
like world objects, have <span class="extract"><span class="extract-syntax">no_allocated_together</span></span> set to 1, and the doubly
linked list is of the objects themselves. For types allocated in small
arrays (typically of 100 objects at a time), <code class="display"><span class="extract-syntax">no_allocated_together</span></code> is set
arrays (typically of 100 objects at a time), <span class="extract"><span class="extract-syntax">no_allocated_together</span></span> is set
to the number of objects in each completed array (so, typically 100) and
the doubly linked list is of the arrays.
</p>
@ -162,7 +162,7 @@ the doubly linked list is of the arrays.
<span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">last_in_memory</span><span class="plain-syntax">; </span><span class="comment"> tail of doubly linked list</span>
<span class="plain-syntax"> </span><span class="comment"> used only to provide statistics for the debugging log:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name_of_type</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"lexicon_entry_MT"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name_of_type</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"lexicon_entry_MT"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">bytes_allocated</span><span class="plain-syntax">; </span><span class="comment"> total allocation for this type of object, not counting overhead</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">objects_count</span><span class="plain-syntax">; </span><span class="comment"> total number currently in existence (i.e., undeleted)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">no_allocated_together</span><span class="plain-syntax">; </span><span class="comment"> number of objects in each array of this type of object</span>
@ -216,15 +216,15 @@ the debugging log.
<span class="definition-keyword">define</span> <span class="constant-syntax">SAFETY_MARGIN</span><span class="plain-syntax"> </span><span class="constant-syntax">128</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">BLANK_END_SIZE</span><span class="plain-syntax"> </span><span class="constant-syntax">256</span>
</pre>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>At present <code class="display"><span class="extract-syntax">MEMORY_GRANULARITY</span></code> is 800K. This is the quantity of memory
allocated by each individual <code class="display"><span class="extract-syntax">malloc</span></code> call.
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>At present <span class="extract"><span class="extract-syntax">MEMORY_GRANULARITY</span></span> is 800K. This is the quantity of memory
allocated by each individual <span class="extract"><span class="extract-syntax">malloc</span></span> call.
</p>
<p class="inwebparagraph">After <code class="display"><span class="extract-syntax">MAX_BLOCKS_ALLOWED</span></code> blocks, we throw in the towel: we must have
<p class="inwebparagraph">After <span class="extract"><span class="extract-syntax">MAX_BLOCKS_ALLOWED</span></span> blocks, we throw in the towel: we must have
fallen into an endless loop which creates endless new objects somewhere.
(If this ever happens, it would be a bug: the point of this mechanism is to
be able to recover. Without this safety measure, OS X in particular would
grind slowly to a halt, never refusing a <code class="display"><span class="extract-syntax">malloc</span></code>, until the user was
grind slowly to a halt, never refusing a <span class="extract"><span class="extract-syntax">malloc</span></span>, until the user was
unable to get the GUI responsive enough to kill the process.)
</p>
@ -238,7 +238,7 @@ unable to get the GUI responsive enough to kill the process.)
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_objects_allocated</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment"> a potentially larger number, used only for the debugging log</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Memory blocks are stored in a linked list, and we keep track of the
size of the current block: that is, the block at the tail of the list.
Each memory block consists of a header structure, followed by <code class="display"><span class="extract-syntax">SAFETY_MARGIN</span></code>
Each memory block consists of a header structure, followed by <span class="extract"><span class="extract-syntax">SAFETY_MARGIN</span></span>
null bytes, followed by actual data.
</p>
@ -272,7 +272,7 @@ pair of routines.
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Add new block to the tail of the list of memory blocks</span> <span class="named-paragraph-number">11.2</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP11_1"></a><b>&#167;11.1. </b>Note that <code class="display"><span class="extract-syntax">cp</span></code> and <code class="display"><span class="extract-syntax">mh</span></code> are set to the same value: they merely have different
</pre><p class="inwebparagraph"><a id="SP11_1"></a><b>&#167;11.1. </b>Note that <span class="extract"><span class="extract-syntax">cp</span></span> and <span class="extract"><span class="extract-syntax">mh</span></span> are set to the same value: they merely have different
pointer types as far as the C compiler is concerned.
</p>
@ -338,7 +338,7 @@ a single large object, or a single array of small objects.
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">memory_frame</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">integrity_check</span><span class="plain-syntax">; </span><span class="comment"> this should always contain the </span><code class="display"><span class="extract-syntax">INTEGRITY_NUMBER</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">integrity_check</span><span class="plain-syntax">; </span><span class="comment"> this should always contain the </span><span class="extract"><span class="extract-syntax">INTEGRITY_NUMBER</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">memory_frame</span><span class="plain-syntax"> *</span><span class="identifier-syntax">next_frame</span><span class="plain-syntax">; </span><span class="comment"> next frame in the list of memory frames</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">mem_type</span><span class="plain-syntax">; </span><span class="comment"> type of object stored in this frame</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">allocation_id</span><span class="plain-syntax">; </span><span class="comment"> allocation ID number of object stored in this frame</span>
@ -353,7 +353,7 @@ blocks, but we don't need to worry about that.)
<span class="reserved-syntax">memory_frame</span><span class="plain-syntax"> *</span><span class="identifier-syntax">last_memory_frame</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment"> most recent memory frame allocated</span>
</pre><p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. </b>If the integrity numbers of every frame are still intact, then it is pretty
unlikely that any bug has caused memory to overwrite one frame into another.
<code class="display"><span class="extract-syntax">Memory::check_memory_integrity</span></code> might on very large runs be run often, if we didn't
<span class="extract"><span class="extract-syntax">Memory::check_memory_integrity</span></span> might on very large runs be run often, if we didn't
prevent this: since the number of calls would be roughly proportional to
memory usage, we would implicitly have an \(O(n^2)\) running time in the
amount of storage \(n\) allocated.
@ -398,7 +398,7 @@ memory frame is created by the following function:
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">bytes_free_in_current_memblock</span><span class="plain-syntax">, </span><span class="identifier-syntax">extent_without_overheads</span><span class="plain-syntax"> = </span><span class="identifier-syntax">extent</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">extent</span><span class="plain-syntax"> += </span><span class="reserved-syntax">sizeof</span><span class="plain-syntax">(</span><span class="reserved-syntax">memory_frame</span><span class="plain-syntax">); </span><span class="comment"> each allocation is preceded by a memory frame</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">extent</span><span class="plain-syntax"> += </span><span class="constant-syntax">SAFETY_MARGIN</span><span class="plain-syntax">; </span><span class="comment"> each allocation is followed by </span><code class="display"><span class="extract-syntax">SAFETY_MARGIN</span></code><span class="comment"> null bytes</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">extent</span><span class="plain-syntax"> += </span><span class="constant-syntax">SAFETY_MARGIN</span><span class="plain-syntax">; </span><span class="comment"> each allocation is followed by </span><span class="extract"><span class="extract-syntax">SAFETY_MARGIN</span></span><span class="comment"> null bytes</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Ensure that the current memory block has room for this many bytes</span> <span class="named-paragraph-number">16.1</span>&gt;<span class="plain-syntax">;</span>
@ -451,7 +451,7 @@ for a user with a particularly long and involved source text to discover.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">first_memory_frame</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">first_memory_frame</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mf</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">last_memory_frame</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next_frame</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mf</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">last_memory_frame</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mf</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-mmr.html#SP16">&#167;16</a>.</li></ul><p class="inwebparagraph"><a id="SP16_3"></a><b>&#167;16.3. </b>See the definition of <code class="display"><span class="extract-syntax">alloc_status</span></code> above.
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-mmr.html#SP16">&#167;16</a>.</li></ul><p class="inwebparagraph"><a id="SP16_3"></a><b>&#167;16.3. </b>See the definition of <span class="extract"><span class="extract-syntax">alloc_status</span></span> above.
</p>
@ -473,9 +473,9 @@ through which all other sections allocate and leaf through memory.
<p class="inwebparagraph">Note that Inweb allows multi-line macro definitions without backslashes
to continue them, unlike ordinary C. Otherwise these are "standard"
macros, though this was my first brush with the <code class="display"><span class="extract-syntax">##</span></code> concatenation
operator: basically <code class="display"><span class="extract-syntax">CREATE(thing)</span></code> expands into <code class="display"><span class="extract-syntax">(allocate_thing())</span></code>
because of the <code class="display"><span class="extract-syntax">##</span></code>. (See Kernighan and Ritchie, section 4.11.2.)
macros, though this was my first brush with the <span class="extract"><span class="extract-syntax">##</span></span> concatenation
operator: basically <span class="extract"><span class="extract-syntax">CREATE(thing)</span></span> expands into <span class="extract"><span class="extract-syntax">(allocate_thing())</span></span>
because of the <span class="extract"><span class="extract-syntax">##</span></span>. (See Kernighan and Ritchie, section 4.11.2.)
</p>
@ -503,12 +503,12 @@ given type.
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="identifier-syntax">var</span><span class="plain-syntax">=</span><span class="identifier-syntax">LAST_OBJECT</span><span class="plain-syntax">(</span><span class="identifier-syntax">type_name</span><span class="plain-syntax">); </span><span class="identifier-syntax">var</span><span class="plain-syntax"> != </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="identifier-syntax">var</span><span class="plain-syntax"> = </span><span class="identifier-syntax">PREV_OBJECT</span><span class="plain-syntax">(</span><span class="identifier-syntax">var</span><span class="plain-syntax">, </span><span class="identifier-syntax">type_name</span><span class="plain-syntax">))</span>
</pre>
<p class="inwebparagraph"><a id="SP19"></a><b>&#167;19. Allocator functions created by macros. </b>The following macros generate a family of systematically named functions.
For instance, we shall shortly expand <code class="display"><span class="extract-syntax">ALLOCATE_INDIVIDUALLY(parse_node)</span></code>,
which will expand to three functions: <code class="display"><span class="extract-syntax">allocate_parse_node</span></code>,
<code class="display"><span class="extract-syntax">deallocate_parse_node</span></code> and <code class="display"><span class="extract-syntax">allocate_parse_node_before</span></code>.
For instance, we shall shortly expand <span class="extract"><span class="extract-syntax">ALLOCATE_INDIVIDUALLY(parse_node)</span></span>,
which will expand to three functions: <span class="extract"><span class="extract-syntax">allocate_parse_node</span></span>,
<span class="extract"><span class="extract-syntax">deallocate_parse_node</span></span> and <span class="extract"><span class="extract-syntax">allocate_parse_node_before</span></span>.
</p>
<p class="inwebparagraph">Quaintly, <code class="display"><span class="extract-syntax">#type_name</span></code> expands into the value of <code class="display"><span class="extract-syntax">type_name</span></code> put within
<p class="inwebparagraph">Quaintly, <span class="extract"><span class="extract-syntax">#type_name</span></span> expands into the value of <span class="extract"><span class="extract-syntax">type_name</span></span> put within
double-quotes.
</p>
@ -578,10 +578,10 @@ double-quotes.
<span class="plain-syntax"> </span><span class="identifier-syntax">UNLOCK_MUTEX</span><span class="plain-syntax">(</span><span class="identifier-syntax">mutex</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="inwebparagraph"><a id="SP20"></a><b>&#167;20. </b><code class="display"><span class="extract-syntax">ALLOCATE_IN_ARRAYS</span></code> is still more obfuscated. When we
<code class="display"><span class="extract-syntax">ALLOCATE_IN_ARRAYS(X, 100)</span></code>, the result will be definitions of a new type
<code class="display"><span class="extract-syntax">X_block</span></code> and functions <code class="display"><span class="extract-syntax">allocate_X</span></code>, <code class="display"><span class="extract-syntax">allocate_X_block</span></code>,
<code class="display"><span class="extract-syntax">deallocate_X_block</span></code> and <code class="display"><span class="extract-syntax">allocate_X_block_before</span></code> (though the last is not
<p class="inwebparagraph"><a id="SP20"></a><b>&#167;20. </b><span class="extract"><span class="extract-syntax">ALLOCATE_IN_ARRAYS</span></span> is still more obfuscated. When we
<span class="extract"><span class="extract-syntax">ALLOCATE_IN_ARRAYS(X, 100)</span></span>, the result will be definitions of a new type
<span class="extract"><span class="extract-syntax">X_block</span></span> and functions <span class="extract"><span class="extract-syntax">allocate_X</span></span>, <span class="extract"><span class="extract-syntax">allocate_X_block</span></span>,
<span class="extract"><span class="extract-syntax">deallocate_X_block</span></span> and <span class="extract"><span class="extract-syntax">allocate_X_block_before</span></span> (though the last is not
destined ever to be used). Note that we are not provided with the means to
deallocate individual objects this time: that's the trade-off for
allocating in blocks.
@ -612,31 +612,31 @@ allocating in blocks.
<span class="plain-syntax"> </span><span class="identifier-syntax">next_</span><span class="plain-syntax">##</span><span class="identifier-syntax">type_name</span><span class="plain-syntax">##</span><span class="identifier-syntax">_array</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">used</span><span class="plain-syntax">++]);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="inwebparagraph"><a id="SP21"></a><b>&#167;21. Expanding many macros. </b>Each given structure must have a typedef name, say <code class="display"><span class="extract-syntax">marvel</span></code>, and can be
<p class="inwebparagraph"><a id="SP21"></a><b>&#167;21. Expanding many macros. </b>Each given structure must have a typedef name, say <span class="extract"><span class="extract-syntax">marvel</span></span>, and can be
used in one of two ways. Either way, we can obtain a new one with the macro
<code class="display"><span class="extract-syntax">CREATE(marvel)</span></code>.
<span class="extract"><span class="extract-syntax">CREATE(marvel)</span></span>.
</p>
<p class="inwebparagraph">Either (a) it will be individually allocated. In this case <code class="display"><span class="extract-syntax">marvel_MT</span></code>
<p class="inwebparagraph">Either (a) it will be individually allocated. In this case <span class="extract"><span class="extract-syntax">marvel_MT</span></span>
should be defined with a new MT (memory type) number, and the macro
<code class="display"><span class="extract-syntax">ALLOCATE_INDIVIDUALLY(marvel)</span></code> should be expanded. The first and last
objects created will be <code class="display"><span class="extract-syntax">FIRST_OBJECT(marvel)</span></code> and <code class="display"><span class="extract-syntax">LAST_OBJECT(marvel)</span></code>,
<span class="extract"><span class="extract-syntax">ALLOCATE_INDIVIDUALLY(marvel)</span></span> should be expanded. The first and last
objects created will be <span class="extract"><span class="extract-syntax">FIRST_OBJECT(marvel)</span></span> and <span class="extract"><span class="extract-syntax">LAST_OBJECT(marvel)</span></span>,
and we can proceed either way through a double linked list of them with
<code class="display"><span class="extract-syntax">PREV_OBJECT(mv, marvel)</span></code> and <code class="display"><span class="extract-syntax">NEXT_OBJECT(mv, marvel)</span></code>. For convenience,
we can loop through marvels, in creation order, using <code class="display"><span class="extract-syntax">LOOP_OVER(var,
</span></code>marvel)<code class="display"><span class="extract-syntax">, which expands to a </span></code>for<code class="display"><span class="extract-syntax"> loop in which the variable </span></code>var<code class="display"><span class="extract-syntax"> runs
</span></code>through each created marvel in turn; or equally we can run backwards
through using <code class="display"><span class="extract-syntax">LOOP_BACKWARDS_OVER(var, marvel)</span></code>. In addition, there are
<span class="extract"><span class="extract-syntax">PREV_OBJECT(mv, marvel)</span></span> and <span class="extract"><span class="extract-syntax">NEXT_OBJECT(mv, marvel)</span></span>. For convenience,
we can loop through marvels, in creation order, using <span class="extract"><span class="extract-syntax">LOOP_OVER(var,
</span></span>marvel)<span class="extract"><span class="extract-syntax">, which expands to a </span></span>for<span class="extract"><span class="extract-syntax"> loop in which the variable </span></span>var<span class="extract"><span class="extract-syntax"> runs
</span></span>through each created marvel in turn; or equally we can run backwards
through using <span class="extract"><span class="extract-syntax">LOOP_BACKWARDS_OVER(var, marvel)</span></span>. In addition, there are
corruption checks to protect the memory from overrunning accidents, and the
structure can be used as a value in the symbols table. Good for large
structures with significant semantic content.
</p>
<p class="inwebparagraph">Or (b) it will be allocated in arrays. Once again we can obtain new marvels
with <code class="display"><span class="extract-syntax">CREATE(marvel)</span></code>. This is more efficient both in speed and memory
with <span class="extract"><span class="extract-syntax">CREATE(marvel)</span></span>. This is more efficient both in speed and memory
usage, but we lose the ability to loop through the objects. For this
arrangement, define <code class="display"><span class="extract-syntax">marvel_array_MT</span></code> with a new MT number and expand the
macro <code class="display"><span class="extract-syntax">ALLOCATE_IN_ARRAYS(marvel, 100)</span></code>, where 100 (or what may you) is the
arrangement, define <span class="extract"><span class="extract-syntax">marvel_array_MT</span></span> with a new MT number and expand the
macro <span class="extract"><span class="extract-syntax">ALLOCATE_IN_ARRAYS(marvel, 100)</span></span>, where 100 (or what may you) is the
number of objects allocated jointly as a block. Good for small structures
used in the lower levels.
</p>
@ -683,7 +683,7 @@ used in the lower levels.
<span class="identifier-syntax">ALLOCATE_IN_ARRAYS</span><span class="plain-syntax">(</span><span class="reserved-syntax">match_trie</span><span class="plain-syntax">, </span><span class="constant-syntax">1000</span><span class="plain-syntax">)</span>
<span class="identifier-syntax">ALLOCATE_IN_ARRAYS</span><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">, </span><span class="constant-syntax">100</span><span class="plain-syntax">)</span>
</pre><p class="inwebparagraph"><a id="SP22"></a><b>&#167;22. Simple memory allocations. </b>Not all of our memory will be claimed in the form of structures: now and then
we need to use the equivalent of traditional <code class="display"><span class="extract-syntax">malloc</span></code> and <code class="display"><span class="extract-syntax">calloc</span></code> routines.
we need to use the equivalent of traditional <span class="extract"><span class="extract-syntax">malloc</span></span> and <span class="extract"><span class="extract-syntax">calloc</span></span> routines.
</p>
@ -730,11 +730,11 @@ claimed" &mdash; the highest recorded net usage count over the run.
<span class="plain-syntax"> </span><span class="identifier-syntax">memory_claimed_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">NO_DEFINED_MREASON_VALUES</span><span class="plain-syntax">],</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">number_of_claims_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">NO_DEFINED_MREASON_VALUES</span><span class="plain-syntax">];</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_claimed_simply</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
</pre><p class="inwebparagraph"><a id="SP25"></a><b>&#167;25. </b>Our allocation routines behave just like the standard C library's <code class="display"><span class="extract-syntax">malloc</span></code>
and <code class="display"><span class="extract-syntax">calloc</span></code>, but where a third argument supplies a reason why the memory is
</pre><p class="inwebparagraph"><a id="SP25"></a><b>&#167;25. </b>Our allocation routines behave just like the standard C library's <span class="extract"><span class="extract-syntax">malloc</span></span>
and <span class="extract"><span class="extract-syntax">calloc</span></span>, but where a third argument supplies a reason why the memory is
needed, and where any failure to allocate memory is tidily dealt with. We will
exit on any such failure, so that the caller can be certain that the return
values of these functions are always non-<code class="display"><span class="extract-syntax">NULL</span></code> pointers.
values of these functions are always non-<span class="extract"><span class="extract-syntax">NULL</span></span> pointers.
</p>
<pre class="displayed-code all-displayed-code">
@ -760,8 +760,8 @@ values of these functions are always non-<code class="display"><span class="extr
<span class="plain-syntax"> </span><span class="identifier-syntax">UNLOCK_MUTEX</span><span class="plain-syntax">(</span><span class="identifier-syntax">mutex</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">pointer</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP26_1"></a><b>&#167;26.1. </b>I am nervous about assuming that <code class="display"><span class="extract-syntax">calloc(0, X)</span></code> returns a non-<code class="display"><span class="extract-syntax">NULL</span></code> pointer
in all implementations of the standard C library, so the case when <code class="display"><span class="extract-syntax">N</span></code> is zero
</pre><p class="inwebparagraph"><a id="SP26_1"></a><b>&#167;26.1. </b>I am nervous about assuming that <span class="extract"><span class="extract-syntax">calloc(0, X)</span></span> returns a non-<span class="extract"><span class="extract-syntax">NULL</span></span> pointer
in all implementations of the standard C library, so the case when <span class="extract"><span class="extract-syntax">N</span></span> is zero
allocates a tiny but positive amount of memory, just to be safe.
</p>
@ -782,7 +782,7 @@ allocates a tiny but positive amount of memory, just to be safe.
<span class="plain-syntax"> </span><a href="3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_C_string</span></a><span class="plain-syntax">(</span><span class="string-syntax">"Out of memory for %s"</span><span class="plain-syntax">, </span><a href="2-mmr.html#SP23" class="function-link"><span class="function-syntax">Memory::description_of_reason</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">R</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-mmr.html#SP26">&#167;26</a>.</li></ul><p class="inwebparagraph"><a id="SP26_2"></a><b>&#167;26.2. </b>These statistics have no function except to improve the diagnostics in the
debugging log, but they are very cheap to keep, since <code class="display"><span class="extract-syntax">Memory::alloc_inner</span></code> is called only
debugging log, but they are very cheap to keep, since <span class="extract"><span class="extract-syntax">Memory::alloc_inner</span></span> is called only
rarely and to allocate large blocks of memory.
</p>
@ -808,7 +808,7 @@ rarely and to allocate large blocks of memory.
<span class="plain-syntax"> </span><span class="identifier-syntax">number_of_claims_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">R</span><span class="plain-syntax">]++;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">memory_claimed_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">R</span><span class="plain-syntax">] &gt; </span><span class="identifier-syntax">max_memory_at_once_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">R</span><span class="plain-syntax">])</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">max_memory_at_once_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">R</span><span class="plain-syntax">] = </span><span class="identifier-syntax">memory_claimed_for_each_need</span><span class="plain-syntax">[</span><span class="identifier-syntax">R</span><span class="plain-syntax">];</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-mmr.html#SP26">&#167;26</a>.</li></ul><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. </b>We also provide our own wrapper for <code class="display"><span class="extract-syntax">free</span></code>:
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-mmr.html#SP26">&#167;26</a>.</li></ul><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. </b>We also provide our own wrapper for <span class="extract"><span class="extract-syntax">free</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -902,7 +902,7 @@ report in the debugging log (for which, see below).
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Sort the table of memory type usages into decreasing size order</span> <span class="named-paragraph-number">32.2</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_for_objects_used</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment"> out of the </span><code class="display"><span class="extract-syntax">total_for_objects</span></code><span class="comment">, the bytes used</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_for_objects_used</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment"> out of the </span><span class="extract"><span class="extract-syntax">total_for_objects</span></span><span class="comment">, the bytes used</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_objects</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Calculate the memory usage for objects</span> <span class="named-paragraph-number">32.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">overhead_for_objects</span><span class="plain-syntax"> = </span><span class="identifier-syntax">total_for_objects</span><span class="plain-syntax"> - </span><span class="identifier-syntax">total_for_objects_used</span><span class="plain-syntax">; </span><span class="comment"> bytes wasted</span>
@ -984,7 +984,7 @@ order of total number of bytes allocated.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">alloc_status</span><span class="plain-syntax">[</span><span class="identifier-syntax">ix2</span><span class="plain-syntax">].</span><span class="element-syntax">bytes_allocated</span><span class="plain-syntax"> - </span><span class="identifier-syntax">alloc_status</span><span class="plain-syntax">[</span><span class="identifier-syntax">ix1</span><span class="plain-syntax">].</span><span class="element-syntax">bytes_allocated</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP34"></a><b>&#167;34. </b>Finally, a little routine to compute the proportions of memory for each
usage. Recall that <code class="display"><span class="extract-syntax">bytes</span></code> is measured in bytes, but <code class="display"><span class="extract-syntax">total</span></code> in kilobytes.
usage. Recall that <span class="extract"><span class="extract-syntax">bytes</span></span> is measured in bytes, but <span class="extract"><span class="extract-syntax">total</span></span> in kilobytes.
</p>
<pre class="displayed-code all-displayed-code">
@ -1003,7 +1003,7 @@ usage. Recall that <code class="display"><span class="extract-syntax">bytes</spa
<span class="plain-syntax"> </span><span class="identifier-syntax">UNLOCK_MUTEX</span><span class="plain-syntax">(</span><span class="identifier-syntax">mutex</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP36"></a><b>&#167;36. Run-time pointer type checking. </b>In several places Inform needs to store pointers of type <code class="display"><span class="extract-syntax">void *</span></code>, that is,
</pre><p class="inwebparagraph"><a id="SP36"></a><b>&#167;36. Run-time pointer type checking. </b>In several places Inform needs to store pointers of type <span class="extract"><span class="extract-syntax">void *</span></span>, that is,
pointers which have no indication of what type of data they point to.
This is not type-safe and therefore offers plenty of opportunity for
blunders. The following provides run-time type checking to ensure that
@ -1011,15 +1011,15 @@ each time we dereference a typeless pointer, it does indeed point to
a structure of the type we think it should.
</p>
<p class="inwebparagraph">The structure <code class="display"><span class="extract-syntax">general_pointer</span></code> holds a <code class="display"><span class="extract-syntax">void *</span></code> pointer to any one of the
<p class="inwebparagraph">The structure <span class="extract"><span class="extract-syntax">general_pointer</span></span> holds a <span class="extract"><span class="extract-syntax">void *</span></span> pointer to any one of the
following:
</p>
</li><li>(a) <code class="display"><span class="extract-syntax">NULL</span></code>, to which we assign ID number \(-1\);
</li><li>(b) <code class="display"><span class="extract-syntax">char</span></code>, to which we assign ID number 1000;
</li><li>(a) <span class="extract"><span class="extract-syntax">NULL</span></span>, to which we assign ID number \(-1\);
</li><li>(b) <span class="extract"><span class="extract-syntax">char</span></span>, to which we assign ID number 1000;
</li><li>(c) any individually allocated structure of the types listed above, to
which we assign the ID numbers used above: for instance, <code class="display"><span class="extract-syntax">blorb_figure_MT</span></code>
is the ID number for a <code class="display"><span class="extract-syntax">general_pointer</span></code> which points to a <code class="display"><span class="extract-syntax">blorb_figure</span></code>
which we assign the ID numbers used above: for instance, <span class="extract"><span class="extract-syntax">blorb_figure_MT</span></span>
is the ID number for a <span class="extract"><span class="extract-syntax">general_pointer</span></span> which points to a <span class="extract"><span class="extract-syntax">blorb_figure</span></span>
structure.
</p>
@ -1037,7 +1037,7 @@ structure.
<span class="reserved-syntax">general_pointer</span><span class="plain-syntax"> </span><span class="function-syntax">Memory::store_gp_null</span><button class="popup" onclick="togglePopup('usagePopup22')">...<span class="popuptext" id="usagePopup22">Usage of <b>Memory::store_gp_null</b>:<br>none</span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">general_pointer</span><span class="plain-syntax"> </span><span class="identifier-syntax">gp</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">gp</span><span class="plain-syntax">.</span><span class="element-syntax">pointer_to_data</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">gp</span><span class="plain-syntax">.</span><span class="element-syntax">run_time_type_code</span><span class="plain-syntax"> = -1; </span><span class="comment"> guaranteed to differ from all </span><code class="display"><span class="extract-syntax">_MT</span></code><span class="comment"> values</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">gp</span><span class="plain-syntax">.</span><span class="element-syntax">run_time_type_code</span><span class="plain-syntax"> = -1; </span><span class="comment"> guaranteed to differ from all </span><span class="extract"><span class="extract-syntax">_MT</span></span><span class="comment"> values</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">gp</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Memory::test_gp_null</span><button class="popup" onclick="togglePopup('usagePopup23')">...<span class="popuptext" id="usagePopup23">Usage of <b>Memory::test_gp_null</b>:<br>none</span></button><span class="plain-syntax">(</span><span class="reserved-syntax">general_pointer</span><span class="plain-syntax"> </span><span class="identifier-syntax">gp</span><span class="plain-syntax">) {</span>
@ -1057,11 +1057,11 @@ objects and to help with interpreting output from GDB, so we abstract that too.
<span class="definition-keyword">define</span> <span class="identifier-syntax">GENERAL_POINTER_AS_INT</span><span class="plain-syntax">(</span><span class="identifier-syntax">gp</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> ((</span><span class="identifier-syntax">pointer_sized_int</span><span class="plain-syntax">) </span><span class="identifier-syntax">gp</span><span class="plain-syntax">.</span><span class="element-syntax">pointer_to_data</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph"><a id="SP38"></a><b>&#167;38. </b>If we have a pointer to <code class="display"><span class="extract-syntax">circus</span></code> (say) then <code class="display"><span class="extract-syntax">g=STORE_POINTER_circus(p)</span></code>
returns a <code class="display"><span class="extract-syntax">general_pointer</span></code> with <code class="display"><span class="extract-syntax">p</span></code> as the actual pointer, but will not
compile unless <code class="display"><span class="extract-syntax">p</span></code> is indeed of type <code class="display"><span class="extract-syntax">circus *</span></code>. When we later
<code class="display"><span class="extract-syntax">RETRIEVE_POINTER_circus(g)</span></code>, an internal error is thrown if <code class="display"><span class="extract-syntax">g</span></code> contains a pointer
which is other than <code class="display"><span class="extract-syntax">void *</span></code>, or which has never been referenced.
<p class="inwebparagraph"><a id="SP38"></a><b>&#167;38. </b>If we have a pointer to <span class="extract"><span class="extract-syntax">circus</span></span> (say) then <span class="extract"><span class="extract-syntax">g=STORE_POINTER_circus(p)</span></span>
returns a <span class="extract"><span class="extract-syntax">general_pointer</span></span> with <span class="extract"><span class="extract-syntax">p</span></span> as the actual pointer, but will not
compile unless <span class="extract"><span class="extract-syntax">p</span></span> is indeed of type <span class="extract"><span class="extract-syntax">circus *</span></span>. When we later
<span class="extract"><span class="extract-syntax">RETRIEVE_POINTER_circus(g)</span></span>, an internal error is thrown if <span class="extract"><span class="extract-syntax">g</span></span> contains a pointer
which is other than <span class="extract"><span class="extract-syntax">void *</span></span>, or which has never been referenced.
</p>
@ -1092,8 +1092,8 @@ which is other than <code class="display"><span class="extract-syntax">void *</s
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="inwebparagraph"><a id="SP39"></a><b>&#167;39. </b>Suitable <code class="display"><span class="extract-syntax">MAKE_REFERENCE_ROUTINES</span></code> were expanded for all of the memory
allocated objects above; so that leaves only humble <code class="display"><span class="extract-syntax">char *</span></code> pointers:
<p class="inwebparagraph"><a id="SP39"></a><b>&#167;39. </b>Suitable <span class="extract"><span class="extract-syntax">MAKE_REFERENCE_ROUTINES</span></span> were expanded for all of the memory
allocated objects above; so that leaves only humble <span class="extract"><span class="extract-syntax">char *</span></span> pointers:
</p>
<pre class="displayed-code all-displayed-code">

40
docs/foundation-module/2-mth.html
View file

@ -68,8 +68,8 @@ the ways that one language differs from another, and they can do that by
providing "methods".
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The model is this. If a <code class="display"><span class="extract-syntax">typedef struct</span></code> definition includes the line
<code class="display"><span class="extract-syntax">METHOD_CALLS</span></code>, then any instance of that structure can have a queue of
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The model is this. If a <span class="extract"><span class="extract-syntax">typedef struct</span></span> definition includes the line
<span class="extract"><span class="extract-syntax">METHOD_CALLS</span></span>, then any instance of that structure can have a queue of
tagged functions attached to it dynamically: those, we'll call "methods".
</p>
@ -95,8 +95,8 @@ tagged functions attached to it dynamically: those, we'll call "methods".
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">S</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure method_set is private to this section.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Declaring methods. </b>Each method is a function, though we don't know its type &mdash; which is why we
resort to the desperate measure of storing it as a <code class="display"><span class="extract-syntax">void *</span></code> &mdash; with an ID
number attached to it. IDs should be from the <code class="display"><span class="extract-syntax">*_MTID</span></code> enumeration set.
resort to the desperate measure of storing it as a <span class="extract"><span class="extract-syntax">void *</span></span> &mdash; with an ID
number attached to it. IDs should be from the <span class="extract"><span class="extract-syntax">*_MTID</span></span> enumeration set.
</p>
@ -108,8 +108,8 @@ of two macros: one for methods returning an integer, one for void methods,
i.e., those returning no value.
</p>
<p class="inwebparagraph">What these do is to use typedef to give the name <code class="display"><span class="extract-syntax">X_type</span></code> to the type of all
functions sharing the method ID <code class="display"><span class="extract-syntax">X</span></code>.
<p class="inwebparagraph">What these do is to use typedef to give the name <span class="extract"><span class="extract-syntax">X_type</span></span> to the type of all
functions sharing the method ID <span class="extract"><span class="extract-syntax">X</span></span>.
</p>
@ -122,7 +122,7 @@ functions sharing the method ID <code class="display"><span class="extract-synta
<pre class="displayed-code all-displayed-code">
<span class="identifier-syntax">IMETHOD_TYPE</span><span class="plain-syntax">(</span><span class="constant-syntax">UNUSED_METHOD_ID_MTID</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">example</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">wont_be_used</span><span class="plain-syntax">)</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. Adding methods. </b>Provided a function has the right type for the ID we're using, we can now
attach it to an object with a method set, using the <code class="display"><span class="extract-syntax">METHOD_ADD</span></code> macro.
attach it to an object with a method set, using the <span class="extract"><span class="extract-syntax">METHOD_ADD</span></span> macro.
(If the type is wrong, the C compiler will throw errors here.)
</p>
@ -163,10 +163,10 @@ attach it to an object with a method set, using the <code class="display"><span
</pre><ul class="endnotetexts"><li>The structure method is private to this section.</li></ul><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Calling methods. </b>Method calls are also done with a macro, but it has to come in four variants:
</p>
</li><li>(a) <code class="display"><span class="extract-syntax">IMETHOD_CALL</span></code> for a method taking arguments and returning an <code class="display"><span class="extract-syntax">int</span></code>,
</li><li>(b) <code class="display"><span class="extract-syntax">IMETHOD_CALLV</span></code> for a method without arguments which returns an <code class="display"><span class="extract-syntax">int</span></code>,
</li><li>(c) <code class="display"><span class="extract-syntax">VMETHOD_CALL</span></code> for a method taking arguments and returning nothing,
</li><li>(d) <code class="display"><span class="extract-syntax">VMETHOD_CALLV</span></code> for a method without arguments which returns nothing.
</li><li>(a) <span class="extract"><span class="extract-syntax">IMETHOD_CALL</span></span> for a method taking arguments and returning an <span class="extract"><span class="extract-syntax">int</span></span>,
</li><li>(b) <span class="extract"><span class="extract-syntax">IMETHOD_CALLV</span></span> for a method without arguments which returns an <span class="extract"><span class="extract-syntax">int</span></span>,
</li><li>(c) <span class="extract"><span class="extract-syntax">VMETHOD_CALL</span></span> for a method taking arguments and returning nothing,
</li><li>(d) <span class="extract"><span class="extract-syntax">VMETHOD_CALLV</span></span> for a method without arguments which returns nothing.
</li></ul>
<p class="inwebparagraph">For example:
</p>
@ -174,19 +174,19 @@ attach it to an object with a method set, using the <code class="display"><span
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">IMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">some_object</span><span class="plain-syntax">, </span><span class="constant-syntax">UNUSED_METHOD_ID_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Hello"</span><span class="plain-syntax">, </span><span class="constant-syntax">17</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph">Note that it's entirely possible for the <code class="display"><span class="extract-syntax">upon</span></code> object to have multiple methods
added for the same ID &mdash; or none. In the <code class="display"><span class="extract-syntax">V</span></code> (void) cases, what we then do is
to call each of them in turn. In the <code class="display"><span class="extract-syntax">I</span></code> (int) cases, we call each in turn, but
stop the moment any of them returns something other than <code class="display"><span class="extract-syntax">FALSE</span></code>, and then
we put that value into the specified result variable <code class="display"><span class="extract-syntax">rval</span></code>.
<p class="inwebparagraph">Note that it's entirely possible for the <span class="extract"><span class="extract-syntax">upon</span></span> object to have multiple methods
added for the same ID &mdash; or none. In the <span class="extract"><span class="extract-syntax">V</span></span> (void) cases, what we then do is
to call each of them in turn. In the <span class="extract"><span class="extract-syntax">I</span></span> (int) cases, we call each in turn, but
stop the moment any of them returns something other than <span class="extract"><span class="extract-syntax">FALSE</span></span>, and then
we put that value into the specified result variable <span class="extract"><span class="extract-syntax">rval</span></span>.
</p>
<p class="inwebparagraph">If <code class="display"><span class="extract-syntax">some_object</span></code> has no methods for the given ID, then nothing happens, and
in the <code class="display"><span class="extract-syntax">I</span></code> case, the return value is <code class="display"><span class="extract-syntax">FALSE</span></code>.
<p class="inwebparagraph">If <span class="extract"><span class="extract-syntax">some_object</span></span> has no methods for the given ID, then nothing happens, and
in the <span class="extract"><span class="extract-syntax">I</span></span> case, the return value is <span class="extract"><span class="extract-syntax">FALSE</span></span>.
</p>
<p class="inwebparagraph">It will, however, produce a compilation error if <code class="display"><span class="extract-syntax">some_object</span></code> is not a pointer
to a structure which has <code class="display"><span class="extract-syntax">METHOD_CALLS</span></code> as part of its definition.
<p class="inwebparagraph">It will, however, produce a compilation error if <span class="extract"><span class="extract-syntax">some_object</span></span> is not a pointer
to a structure which has <span class="extract"><span class="extract-syntax">METHOD_CALLS</span></span> as part of its definition.
</p>

164
docs/foundation-module/2-str.html
View file

@ -74,16 +74,16 @@ is composed to a single code point as E-acute.
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">NEWLINE_IN_STRING</span><span class="plain-syntax"> ((</span><span class="reserved-syntax">char</span><span class="plain-syntax">) </span><span class="constant-syntax">0x7f</span><span class="plain-syntax">) </span><span class="comment"> Within quoted text, all newlines are converted to this</span>
</pre>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The <code class="display"><span class="extract-syntax">text_stream</span></code> type began as a generalisation of the standard C library's
<code class="display"><span class="extract-syntax">FILE</span></code>, and it is used in mostly similar ways. The user &mdash; the whole
program outside of this section &mdash; deals only with <code class="display"><span class="extract-syntax">text_stream *</span></code> pointers to
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The <span class="extract"><span class="extract-syntax">text_stream</span></span> type began as a generalisation of the standard C library's
<span class="extract"><span class="extract-syntax">FILE</span></span>, and it is used in mostly similar ways. The user &mdash; the whole
program outside of this section &mdash; deals only with <span class="extract"><span class="extract-syntax">text_stream *</span></span> pointers to
represent streams in use.
</p>
<p class="inwebparagraph">All stream handling is defined via macros. While many operations could be
handled by ordinary functions, others cannot. <code class="display"><span class="extract-syntax">text_stream</span></code> cannot have exactly
the semantics of <code class="display"><span class="extract-syntax">FILE</span></code> since we cannot rely on the host operating system
to allocate and deallocate the structures behind <code class="display"><span class="extract-syntax">text_stream *</span></code> pointers; and
handled by ordinary functions, others cannot. <span class="extract"><span class="extract-syntax">text_stream</span></span> cannot have exactly
the semantics of <span class="extract"><span class="extract-syntax">FILE</span></span> since we cannot rely on the host operating system
to allocate and deallocate the structures behind <span class="extract"><span class="extract-syntax">text_stream *</span></span> pointers; and
we cannot use our own memory system, either, since we need stream handling
to work both before the memory allocator starts and after it has finished.
Our macros allow us to hide all this. Besides that, a macro approach makes it
@ -95,15 +95,15 @@ implementation is the second stab at it.)
with code ordering if we leave them until later. They are written in the
old-fashioned way, for compatibility with old copies of GCC, and avoid the
need for comma deletion around empty tokens, as that is a point of
incompatibility between implementations of the C preprocessor <code class="display"><span class="extract-syntax">cpp</span></code>. All the
incompatibility between implementations of the C preprocessor <span class="extract"><span class="extract-syntax">cpp</span></span>. All the
same, if you're porting this code, you may need to rewrite the macro with
<code class="display"><span class="extract-syntax">...</span></code> in place of <code class="display"><span class="extract-syntax">args...</span></code> in the header, and then <code class="display"><span class="extract-syntax">__VA_ARGS__</span></code> in place
of <code class="display"><span class="extract-syntax">args</span></code> in the definition: that being the modern way, apparently.
<span class="extract"><span class="extract-syntax">...</span></span> in place of <span class="extract"><span class="extract-syntax">args...</span></span> in the header, and then <span class="extract"><span class="extract-syntax">__VA_ARGS__</span></span> in place
of <span class="extract"><span class="extract-syntax">args</span></span> in the definition: that being the modern way, apparently.
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">WRITE</span></code> is essentially <code class="display"><span class="extract-syntax">sprintf</span></code> and <code class="display"><span class="extract-syntax">fprintf</span></code> combined, since it prints
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">WRITE</span></span> is essentially <span class="extract"><span class="extract-syntax">sprintf</span></span> and <span class="extract"><span class="extract-syntax">fprintf</span></span> combined, since it prints
formatted text to the current stream, which could be either a string or a
file. <code class="display"><span class="extract-syntax">PRINT</span></code> does the same but to <code class="display"><span class="extract-syntax">STDOUT</span></code>, and is thus essentially <code class="display"><span class="extract-syntax">printf</span></code>.
file. <span class="extract"><span class="extract-syntax">PRINT</span></span> does the same but to <span class="extract"><span class="extract-syntax">STDOUT</span></span>, and is thus essentially <span class="extract"><span class="extract-syntax">printf</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -120,8 +120,8 @@ file. <code class="display"><span class="extract-syntax">PRINT</span></code> doe
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The main purpose of many functions is to write textual material to some
file. Such functions almost always have a special argument in their
prototypes: <code class="display"><span class="extract-syntax">OUTPUT_STREAM</span></code>. This tells them where to pipe their output, which
is always to a "current stream" called <code class="display"><span class="extract-syntax">OUT</span></code>. What this leads to, and who will
prototypes: <span class="extract"><span class="extract-syntax">OUTPUT_STREAM</span></span>. This tells them where to pipe their output, which
is always to a "current stream" called <span class="extract"><span class="extract-syntax">OUT</span></span>. What this leads to, and who will
see that it's properly opened and closed, are not their concern.
</p>
@ -129,19 +129,19 @@ see that it's properly opened and closed, are not their concern.
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax"> </span><span class="comment"> used only as a function prototype argument</span>
</pre>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>Three output streams are always open. One is <code class="display"><span class="extract-syntax">NULL</span></code>, that is, its value
as a <code class="display"><span class="extract-syntax">text_stream *</span></code> pointer is <code class="display"><span class="extract-syntax">NULL</span></code>, the generic C null pointer. This represents
an oubliette: it is entirely valid to use it, but output sent to <code class="display"><span class="extract-syntax">NULL</span></code> will
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>Three output streams are always open. One is <span class="extract"><span class="extract-syntax">NULL</span></span>, that is, its value
as a <span class="extract"><span class="extract-syntax">text_stream *</span></span> pointer is <span class="extract"><span class="extract-syntax">NULL</span></span>, the generic C null pointer. This represents
an oubliette: it is entirely valid to use it, but output sent to <span class="extract"><span class="extract-syntax">NULL</span></span> will
never be seen again.
</p>
<p class="inwebparagraph">The others are <code class="display"><span class="extract-syntax">STDOUT</span></code> and <code class="display"><span class="extract-syntax">STDERR</span></code>. As the names suggest these are wrappers
for <code class="display"><span class="extract-syntax">stdout</span></code> and <code class="display"><span class="extract-syntax">stderr</span></code>, the standard console output and error messages
<p class="inwebparagraph">The others are <span class="extract"><span class="extract-syntax">STDOUT</span></span> and <span class="extract"><span class="extract-syntax">STDERR</span></span>. As the names suggest these are wrappers
for <span class="extract"><span class="extract-syntax">stdout</span></span> and <span class="extract"><span class="extract-syntax">stderr</span></span>, the standard console output and error messages
"files" provided by the C library.
</p>
<p class="inwebparagraph">We should always use <code class="display"><span class="extract-syntax">PRINT(...)</span></code> instead of <code class="display"><span class="extract-syntax">printf(...)</span></code> for console output,
so that there are no uses of <code class="display"><span class="extract-syntax">printf</span></code> anywhere in the program.
<p class="inwebparagraph">We should always use <span class="extract"><span class="extract-syntax">PRINT(...)</span></span> instead of <span class="extract"><span class="extract-syntax">printf(...)</span></span> for console output,
so that there are no uses of <span class="extract"><span class="extract-syntax">printf</span></span> anywhere in the program.
</p>
@ -149,10 +149,10 @@ so that there are no uses of <code class="display"><span class="extract-syntax">
<span class="definition-keyword">define</span> <span class="constant-syntax">STDOUT</span><span class="plain-syntax"> </span><a href="2-str.html#SP22" class="function-link"><span class="function-syntax">Streams::get_stdout</span></a><span class="plain-syntax">()</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">STDERR</span><span class="plain-syntax"> </span><a href="2-str.html#SP23" class="function-link"><span class="function-syntax">Streams::get_stderr</span></a><span class="plain-syntax">()</span>
</pre>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b><code class="display"><span class="extract-syntax">PUT</span></code> and <code class="display"><span class="extract-syntax">PUT_TO</span></code> similarly print single characters, which are
specified as unsigned integer values. In practice, <code class="display"><span class="extract-syntax">WRITE_TO</span></code> and
<code class="display"><span class="extract-syntax">PUT_TO</span></code> are seldom needed because there is almost always only one
stream of interest at a time &mdash; <code class="display"><span class="extract-syntax">OUT</span></code>, the current stream.
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b><span class="extract"><span class="extract-syntax">PUT</span></span> and <span class="extract"><span class="extract-syntax">PUT_TO</span></span> similarly print single characters, which are
specified as unsigned integer values. In practice, <span class="extract"><span class="extract-syntax">WRITE_TO</span></span> and
<span class="extract"><span class="extract-syntax">PUT_TO</span></span> are seldom needed because there is almost always only one
stream of interest at a time &mdash; <span class="extract"><span class="extract-syntax">OUT</span></span>, the current stream.
</p>
@ -176,7 +176,7 @@ to become negative.
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>Other streams only exist when explicitly created, or "opened". A function
is only allowed to open a new stream if it can be proved that this stream will
always subsequently be "closed". (Except for the possibility of the tool
halting with an internal error, and therefore an <code class="display"><span class="extract-syntax">exit(1)</span></code>, while the stream
halting with an internal error, and therefore an <span class="extract"><span class="extract-syntax">exit(1)</span></span>, while the stream
is still open.) A stream can be opened and closed only once, and outside that
time its state is undefined: it must not be used at all.
</p>
@ -184,18 +184,18 @@ time its state is undefined: it must not be used at all.
<p class="inwebparagraph">The simplest way is to make a temporary stream, which can be used as a sort
of clipboard. For instance, suppose we have to compile X before Y, but have to
ensure Y comes before X in the eventual output. We create a temporary stream,
compile X into it, then compile Y to <code class="display"><span class="extract-syntax">OUT</span></code>, then copy the temporary stream
into <code class="display"><span class="extract-syntax">OUT</span></code> and dispose of it.
compile X into it, then compile Y to <span class="extract"><span class="extract-syntax">OUT</span></span>, then copy the temporary stream
into <span class="extract"><span class="extract-syntax">OUT</span></span> and dispose of it.
</p>
<p class="inwebparagraph">Temporary streams are always created in memory, held in C's local stack frame
rather than allocated and freed via <code class="display"><span class="extract-syntax">malloc</span></code> and <code class="display"><span class="extract-syntax">free</span></code>. It must always be
possible to prove that execution passes from <code class="display"><span class="extract-syntax">TEMPORARY_TEXT</span></code> to
<code class="display"><span class="extract-syntax">DISCARD_TEXT</span></code>, unless the program makes a fatal exit in between. The stream,
let's call it <code class="display"><span class="extract-syntax">TEMP</span></code>, exists only between those macros. We can legitimately
rather than allocated and freed via <span class="extract"><span class="extract-syntax">malloc</span></span> and <span class="extract"><span class="extract-syntax">free</span></span>. It must always be
possible to prove that execution passes from <span class="extract"><span class="extract-syntax">TEMPORARY_TEXT</span></span> to
<span class="extract"><span class="extract-syntax">DISCARD_TEXT</span></span>, unless the program makes a fatal exit in between. The stream,
let's call it <span class="extract"><span class="extract-syntax">TEMP</span></span>, exists only between those macros. We can legitimately
create a temporary stream many times in one function (for instance inside a
loop body) because each time <code class="display"><span class="extract-syntax">TEMP</span></code> is created as a new stream, overwriting the
old one. <code class="display"><span class="extract-syntax">TEMP</span></code> is a different stream each time it is created, so it does
loop body) because each time <span class="extract"><span class="extract-syntax">TEMP</span></span> is created as a new stream, overwriting the
old one. <span class="extract"><span class="extract-syntax">TEMP</span></span> is a different stream each time it is created, so it does
not violate the rule that every stream is opened and closed once only.
</p>
@ -210,14 +210,14 @@ not violate the rule that every stream is opened and closed once only.
</pre>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Otherwise we can create new globally existing streams, provided we take on
the responsibility for seeing that they are properly closed. There are two
choices: a stream in memory, allocated via <code class="display"><span class="extract-syntax">malloc</span></code> and freed by <code class="display"><span class="extract-syntax">free</span></code> when
the stream is closed; or a file written to disc, opened via <code class="display"><span class="extract-syntax">fopen</span></code> and
later closed by <code class="display"><span class="extract-syntax">fclose</span></code>. Files are always written in text mode, that is,
<code class="display"><span class="extract-syntax">"w"</span></code> not <code class="display"><span class="extract-syntax">"wb"</span></code>, for those platforms where this makes a difference.
choices: a stream in memory, allocated via <span class="extract"><span class="extract-syntax">malloc</span></span> and freed by <span class="extract"><span class="extract-syntax">free</span></span> when
the stream is closed; or a file written to disc, opened via <span class="extract"><span class="extract-syntax">fopen</span></span> and
later closed by <span class="extract"><span class="extract-syntax">fclose</span></span>. Files are always written in text mode, that is,
<span class="extract"><span class="extract-syntax">"w"</span></span> not <span class="extract"><span class="extract-syntax">"wb"</span></span>, for those platforms where this makes a difference.
</p>
<p class="inwebparagraph">We use streams to handle all of our text file output, so there should be no
calls to <code class="display"><span class="extract-syntax">fprintf</span></code> anywhere in the program except for binary files.
calls to <span class="extract"><span class="extract-syntax">fprintf</span></span> anywhere in the program except for binary files.
</p>
@ -227,7 +227,7 @@ calls to <code class="display"><span class="extract-syntax">fprintf</span></code
<span class="definition-keyword">define</span> <span class="identifier-syntax">STREAM_OPEN_IN_MEMORY</span><span class="plain-syntax">(</span><span class="identifier-syntax">new</span><span class="plain-syntax">) </span><a href="2-str.html#SP26" class="function-link"><span class="function-syntax">Streams::open_to_memory</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">new</span><span class="plain-syntax">, </span><span class="constant-syntax">20480</span><span class="plain-syntax">)</span>
<span class="definition-keyword">define</span> <span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">stream</span><span class="plain-syntax">) </span><a href="2-str.html#SP34" class="function-link"><span class="function-syntax">Streams::close</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">stream</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>The following operation is equivalent to <code class="display"><span class="extract-syntax">fflush</span></code> and makes it more likely
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>The following operation is equivalent to <span class="extract"><span class="extract-syntax">fflush</span></span> and makes it more likely
(I put it no higher) that the text written to a stream has all actually been
copied onto the disc, rather than sitting in some operating system buffer.
This helps ensure that any debugging log is up to the minute, in case of
@ -241,7 +241,7 @@ a memory stream is legal but does nothing.
</pre>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>A piece of information we can read for any stream is the number of characters
written to it: its "extent". In fact, UTF-8 multi-byte encoding schemes,
together with differing platform interpretations of C's <code class="display"><span class="extract-syntax">'\n'</span></code>, mean that this
together with differing platform interpretations of C's <span class="extract"><span class="extract-syntax">'\n'</span></span>, mean that this
extent is not necessarily either the final file size in bytes or the final
number of human-readable characters. We will only actually use it to detect
whether text has, or has not, been written to a stream between two points in
@ -253,7 +253,7 @@ time, by seeing whether or not it has increased.
<span class="definition-keyword">define</span> <span class="identifier-syntax">STREAM_EXTENT</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) </span><a href="2-str.html#SP38" class="function-link"><span class="function-syntax">Streams::get_position</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>The remaining operations are available only for streams in memory (well, and
for <code class="display"><span class="extract-syntax">NULL</span></code>, but of course they do nothing when applied to that). While they
for <span class="extract"><span class="extract-syntax">NULL</span></span>, but of course they do nothing when applied to that). While they
could be provided for file streams, this would be so inefficient that we will
pretend it is impossible. Any function which might need to use one
of these operations should open with the following sentinel macro:
@ -284,24 +284,24 @@ stream).
<span class="definition-keyword">define</span> <span class="identifier-syntax">STREAM_MOST_RECENT_CHAR</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) </span><a href="2-str.html#SP39" class="function-link"><span class="function-syntax">Streams::latest</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">)</span>
<span class="definition-keyword">define</span> <span class="identifier-syntax">STREAM_COPY</span><span class="plain-syntax">(</span><span class="identifier-syntax">to</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">) </span><a href="2-str.html#SP42" class="function-link"><span class="function-syntax">Streams::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">to</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. </b>So much for the definition; now the implementation. Here is the <code class="display"><span class="extract-syntax">text_stream</span></code>
<p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. </b>So much for the definition; now the implementation. Here is the <span class="extract"><span class="extract-syntax">text_stream</span></span>
structure. Open memory streams are represented by structures where
<code class="display"><span class="extract-syntax">write_to_memory</span></code> is valid, open file streams by those where <code class="display"><span class="extract-syntax">write_to_file</span></code>
is valid. That counts every open stream except <code class="display"><span class="extract-syntax">NULL</span></code>, which of course
doesn't point to a <code class="display"><span class="extract-syntax">text_stream</span></code> structure at all.
<span class="extract"><span class="extract-syntax">write_to_memory</span></span> is valid, open file streams by those where <span class="extract"><span class="extract-syntax">write_to_file</span></span>
is valid. That counts every open stream except <span class="extract"><span class="extract-syntax">NULL</span></span>, which of course
doesn't point to a <span class="extract"><span class="extract-syntax">text_stream</span></span> structure at all.
</p>
<p class="inwebparagraph">Any stream can have <code class="display"><span class="extract-syntax">USES_XML_ESCAPES_STRF</span></code> set or cleared. When this is set, the
XML (and HTML) escapes of <code class="display"><span class="extract-syntax">&amp;amp;</span></code> for ampersand, and <code class="display"><span class="extract-syntax">&amp;lt;</span></code> and <code class="display"><span class="extract-syntax">&amp;gt;</span></code> for
<p class="inwebparagraph">Any stream can have <span class="extract"><span class="extract-syntax">USES_XML_ESCAPES_STRF</span></span> set or cleared. When this is set, the
XML (and HTML) escapes of <span class="extract"><span class="extract-syntax">&amp;amp;</span></span> for ampersand, and <span class="extract"><span class="extract-syntax">&amp;lt;</span></span> and <span class="extract"><span class="extract-syntax">&amp;gt;</span></span> for
angle brackets, will be used automatically on writing. By default this flag
is clear, that is, no conversion is made.
</p>
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">MALLOCED_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000001</span><span class="plain-syntax"> </span><span class="comment"> was the </span><code class="display"><span class="extract-syntax">write_to_memory</span></code><span class="comment"> pointer claimed by </span><code class="display"><span class="extract-syntax">malloc</span></code><span class="comment">?</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">MALLOCED_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000001</span><span class="plain-syntax"> </span><span class="comment"> was the </span><span class="extract"><span class="extract-syntax">write_to_memory</span></span><span class="comment"> pointer claimed by </span><span class="extract"><span class="extract-syntax">malloc</span></span><span class="comment">?</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">USES_XML_ESCAPES_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000002</span><span class="plain-syntax"> </span><span class="comment"> see above</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">USES_LOG_ESCAPES_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000004</span><span class="plain-syntax"> </span><span class="comment"> </span><code class="display"><span class="extract-syntax">WRITE</span></code><span class="comment"> to this stream supports </span><code class="display"><span class="extract-syntax">$</span></code><span class="comment"> escapes</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">USES_LOG_ESCAPES_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000004</span><span class="plain-syntax"> </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">WRITE</span></span><span class="comment"> to this stream supports </span><span class="extract"><span class="extract-syntax">$</span></span><span class="comment"> escapes</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">INDENT_PENDING_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000008</span><span class="plain-syntax"> </span><span class="comment"> we have just ended a line, so further text should indent</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">FILE_ENCODING_ISO_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000010</span><span class="plain-syntax"> </span><span class="comment"> relevant only for file streams</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">FILE_ENCODING_UTF8_STRF</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000020</span><span class="plain-syntax"> </span><span class="comment"> relevant only for file streams</span>
@ -317,12 +317,12 @@ is clear, that is, no conversion is made.
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">stream_flags</span><span class="plain-syntax">; </span><span class="comment"> bitmap of the </span><code class="display"><span class="extract-syntax">*_STRF</span></code><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">FILE</span><span class="plain-syntax"> *</span><span class="identifier-syntax">write_to_file</span><span class="plain-syntax">; </span><span class="comment"> for an open stream, exactly one of these is </span><code class="display"><span class="extract-syntax">NULL</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">HTML_file_state</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_HTML</span><span class="plain-syntax">; </span><span class="comment"> relevant only to the </span><code class="display"><span class="extract-syntax">HTML::</span></code><span class="comment"> section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">stream_flags</span><span class="plain-syntax">; </span><span class="comment"> bitmap of the </span><span class="extract"><span class="extract-syntax">*_STRF</span></span><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">FILE</span><span class="plain-syntax"> *</span><span class="identifier-syntax">write_to_file</span><span class="plain-syntax">; </span><span class="comment"> for an open stream, exactly one of these is </span><span class="extract"><span class="extract-syntax">NULL</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">HTML_file_state</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_HTML</span><span class="plain-syntax">; </span><span class="comment"> relevant only to the </span><span class="extract"><span class="extract-syntax">HTML::</span></span><span class="comment"> section</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> *</span><span class="identifier-syntax">write_to_memory</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">file_written</span><span class="plain-syntax">; </span><span class="comment"> ditto</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chars_written</span><span class="plain-syntax">; </span><span class="comment"> number of characters sent, counting </span><code class="display"><span class="extract-syntax">\n</span></code><span class="comment"> as 1</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chars_written</span><span class="plain-syntax">; </span><span class="comment"> number of characters sent, counting </span><span class="extract"><span class="extract-syntax">\n</span></span><span class="comment"> as 1</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chars_capacity</span><span class="plain-syntax">; </span><span class="comment"> maximum number the stream can accept without claiming more resources</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">stream_continues</span><span class="plain-syntax">; </span><span class="comment"> if one memory stream is extended by another</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">;</span>
@ -333,10 +333,10 @@ is clear, that is, no conversion is made.
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="identifier-syntax">STREAM_USES_UTF8</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) ((</span><span class="identifier-syntax">x</span><span class="plain-syntax">)?((</span><span class="identifier-syntax">x</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stream_flags</span><span class="plain-syntax">) &amp; </span><span class="constant-syntax">FILE_ENCODING_UTF8_STRF</span><span class="plain-syntax">):</span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>When text is stored at <code class="display"><span class="extract-syntax">write_to_memory</span></code>, it is kept as a zero-terminated C
<p class="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>When text is stored at <span class="extract"><span class="extract-syntax">write_to_memory</span></span>, it is kept as a zero-terminated C
wide string, with one word per Unicode code point. It turns out to be
efficient to preserve a small margin of clear space at the end of the space,
so out of the <code class="display"><span class="extract-syntax">chars_capacity</span></code> space, the following amount will be kept clear:
so out of the <span class="extract"><span class="extract-syntax">chars_capacity</span></span> space, the following amount will be kept clear:
</p>
@ -373,7 +373,7 @@ truncated and we will shed no tears.
<span class="plain-syntax"> </span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">file_written</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP20"></a><b>&#167;20. </b>Any stream can have the following flag set or cleared. When this is set, the
XML (and HTML) escapes of <code class="display"><span class="extract-syntax">&amp;amp;</span></code> for ampersand, and <code class="display"><span class="extract-syntax">&amp;lt;</span></code> and <code class="display"><span class="extract-syntax">&amp;gt;</span></code> for
XML (and HTML) escapes of <span class="extract"><span class="extract-syntax">&amp;amp;</span></span> for ampersand, and <span class="extract"><span class="extract-syntax">&amp;lt;</span></span> and <span class="extract"><span class="extract-syntax">&amp;gt;</span></span> for
angle brackets, will be used automatically on writing. By default this flag
is clear, that is, no conversion is made.
</p>
@ -443,8 +443,8 @@ is clear, that is, no conversion is made.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">")"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP22"></a><b>&#167;22. Standard I/O wrappers. </b>The first call to <code class="display"><span class="extract-syntax">Streams::get_stdout()</span></code> creates a suitable wrapper for <code class="display"><span class="extract-syntax">stdout</span></code>
and returns a <code class="display"><span class="extract-syntax">text_stream *</span></code> pointer to it; subsequent calls just return this wrapper.
</pre><p class="inwebparagraph"><a id="SP22"></a><b>&#167;22. Standard I/O wrappers. </b>The first call to <span class="extract"><span class="extract-syntax">Streams::get_stdout()</span></span> creates a suitable wrapper for <span class="extract"><span class="extract-syntax">stdout</span></span>
and returns a <span class="extract"><span class="extract-syntax">text_stream *</span></span> pointer to it; subsequent calls just return this wrapper.
</p>
<pre class="displayed-code all-displayed-code">
@ -481,7 +481,7 @@ and returns a <code class="display"><span class="extract-syntax">text_stream *</
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> &amp;</span><span class="identifier-syntax">STDERR_struct</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP24"></a><b>&#167;24. Creating file streams. </b>Note that this can fail, if the host filing system refuses to open the file,
so we return <code class="display"><span class="extract-syntax">TRUE</span></code> if and only if successful.
so we return <span class="extract"><span class="extract-syntax">TRUE</span></span> if and only if successful.
</p>
<pre class="displayed-code all-displayed-code">
@ -518,7 +518,7 @@ so we return <code class="display"><span class="extract-syntax">TRUE</span></cod
<span class="plain-syntax"> </span><span class="identifier-syntax">total_file_writes</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP26"></a><b>&#167;26. Creating memory streams. </b>Here we have a choice. One option is to use <code class="display"><span class="extract-syntax">malloc</span></code> to allocate memory to hold
</pre><p class="inwebparagraph"><a id="SP26"></a><b>&#167;26. Creating memory streams. </b>Here we have a choice. One option is to use <span class="extract"><span class="extract-syntax">malloc</span></span> to allocate memory to hold
the text of the stream; this too can fail for host platform reasons, so again
we return a success code.
</p>
@ -538,7 +538,7 @@ we return a success code.
<span class="plain-syntax"> </span><span class="identifier-syntax">UNLOCK_MUTEX</span><span class="plain-syntax">(</span><span class="identifier-syntax">mutex</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. </b>The other option avoids <code class="display"><span class="extract-syntax">malloc</span></code> by using specific storage already available.
</pre><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. </b>The other option avoids <span class="extract"><span class="extract-syntax">malloc</span></span> by using specific storage already available.
If called validly, this cannot fail.
</p>
@ -636,7 +636,7 @@ page of the Unicode set, null terminated):
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">C_string</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP30"></a><b>&#167;30. </b>Unicode code points outside the first page are flattened to <code class="display"><span class="extract-syntax">'?'</span></code> in an
</pre><p class="inwebparagraph"><a id="SP30"></a><b>&#167;30. </b>Unicode code points outside the first page are flattened to <span class="extract"><span class="extract-syntax">'?'</span></span> in an
ISO string:
</p>
@ -716,7 +716,7 @@ ISO string:
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP33"></a><b>&#167;33. Flush and close. </b>Note that flush is an operation which can be performed on any stream, including
<code class="display"><span class="extract-syntax">NULL</span></code>:
<span class="extract"><span class="extract-syntax">NULL</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -724,7 +724,7 @@ ISO string:
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">stream</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">write_to_file</span><span class="plain-syntax">) </span><span class="identifier-syntax">fflush</span><span class="plain-syntax">(</span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">write_to_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP34"></a><b>&#167;34. </b>But closing is not allowed for <code class="display"><span class="extract-syntax">NULL</span></code> or the standard I/O wrappers:
</pre><p class="inwebparagraph"><a id="SP34"></a><b>&#167;34. </b>But closing is not allowed for <span class="extract"><span class="extract-syntax">NULL</span></span> or the standard I/O wrappers:
</p>
<pre class="displayed-code all-displayed-code">
@ -746,7 +746,7 @@ was supplied by our client; it only needs freeing if we were the ones who
allocated it.
</p>
<p class="inwebparagraph">Inscrutably, <code class="display"><span class="extract-syntax">fclose</span></code> returns <code class="display"><span class="extract-syntax">EOF</span></code> to report any failure.
<p class="inwebparagraph">Inscrutably, <span class="extract"><span class="extract-syntax">fclose</span></span> returns <span class="extract"><span class="extract-syntax">EOF</span></span> to report any failure.
</p>
@ -765,12 +765,12 @@ allocated it.
<span class="plain-syntax"> </span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">write_to_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-str.html#SP34">&#167;34</a>.</li></ul><p class="inwebparagraph"><a id="SP34_2"></a><b>&#167;34.2. </b>Note that we need do nothing to close a memory stream when the storage
was supplied by our client; it only needs freeing if we were the ones who
allocated it. <code class="display"><span class="extract-syntax">free</span></code> is a void function; in theory it cannot fail, if
allocated it. <span class="extract"><span class="extract-syntax">free</span></span> is a void function; in theory it cannot fail, if
supplied a valid argument.
</p>
<p class="inwebparagraph">We have to be very careful once we have called <code class="display"><span class="extract-syntax">free</span></code>, because that memory
may well contain the <code class="display"><span class="extract-syntax">text_stream</span></code> structure to which <code class="display"><span class="extract-syntax">stream</span></code> points &mdash; see
<p class="inwebparagraph">We have to be very careful once we have called <span class="extract"><span class="extract-syntax">free</span></span>, because that memory
may well contain the <span class="extract"><span class="extract-syntax">text_stream</span></span> structure to which <span class="extract"><span class="extract-syntax">stream</span></span> points &mdash; see
how continuations are made, below.
</p>
@ -786,7 +786,7 @@ how continuations are made, below.
<span class="plain-syntax"> </span><a href="2-mmr.html#SP27" class="function-link"><span class="function-syntax">Memory::I7_free</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mem</span><span class="plain-syntax">, </span><span class="constant-syntax">STREAM_MREASON</span><span class="plain-syntax">, </span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">chars_capacity</span><span class="plain-syntax">*((</span><span class="reserved-syntax">int</span><span class="plain-syntax">) </span><span class="reserved-syntax">sizeof</span><span class="plain-syntax">(</span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax">)));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stream</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-str.html#SP34">&#167;34</a>.</li></ul><p class="inwebparagraph"><a id="SP35"></a><b>&#167;35. Writing. </b>Our equivalent of <code class="display"><span class="extract-syntax">fputc</span></code> reads:
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-str.html#SP34">&#167;34</a>.</li></ul><p class="inwebparagraph"><a id="SP35"></a><b>&#167;35. Writing. </b>Our equivalent of <span class="extract"><span class="extract-syntax">fputc</span></span> reads:
</p>
<pre class="displayed-code all-displayed-code">
@ -855,20 +855,20 @@ how continuations are made, below.
<span class="plain-syntax"> </span><a href="2-str.html#SP35" class="function-link"><span class="function-syntax">Streams::putc</span></a><span class="plain-syntax">(</span><span class="character-syntax">' '</span><span class="plain-syntax">, </span><span class="identifier-syntax">first_stream</span><span class="plain-syntax">); </span><a href="2-str.html#SP35" class="function-link"><span class="function-syntax">Streams::putc</span></a><span class="plain-syntax">(</span><span class="character-syntax">' '</span><span class="plain-syntax">, </span><span class="identifier-syntax">first_stream</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-str.html#SP35">&#167;35</a>.</li></ul><p class="inwebparagraph"><a id="SP35_3"></a><b>&#167;35.3. </b>The following is checked before any numerical <code class="display"><span class="extract-syntax">printf</span></code>-style escape is expanded
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-str.html#SP35">&#167;35</a>.</li></ul><p class="inwebparagraph"><a id="SP35_3"></a><b>&#167;35.3. </b>The following is checked before any numerical <span class="extract"><span class="extract-syntax">printf</span></span>-style escape is expanded
into the stream, or before any single character is written. Thus we cannot
overrun our buffers unless the expansion of a numerical escape exceeds
<code class="display"><span class="extract-syntax">SPACE_AT_END_OF_STREAM</span></code> plus 1 in size. Since no outside influence gets to
choose what formatting escapes we use (so that <code class="display"><span class="extract-syntax">%3000d</span></code>, say, can't occur),
<span class="extract"><span class="extract-syntax">SPACE_AT_END_OF_STREAM</span></span> plus 1 in size. Since no outside influence gets to
choose what formatting escapes we use (so that <span class="extract"><span class="extract-syntax">%3000d</span></span>, say, can't occur),
we can be pretty confident.
</p>
<p class="inwebparagraph">The interesting case occurs when we run out of memory in a memory stream.
We make a continuation to a fresh <code class="display"><span class="extract-syntax">text_stream</span></code> structure, which points to twice
as much memory as the original, allocated via <code class="display"><span class="extract-syntax">malloc</span></code>. (We will actually need
We make a continuation to a fresh <span class="extract"><span class="extract-syntax">text_stream</span></span> structure, which points to twice
as much memory as the original, allocated via <span class="extract"><span class="extract-syntax">malloc</span></span>. (We will actually need
a little more memory than that because we also have to make room for the
<code class="display"><span class="extract-syntax">text_stream</span></code> structure itself.) We then set <code class="display"><span class="extract-syntax">stream</span></code> to the <code class="display"><span class="extract-syntax">continuation</span></code>. Given
that <code class="display"><span class="extract-syntax">malloc</span></code> was successful &mdash; and it must have been or we would have stopped
<span class="extract"><span class="extract-syntax">text_stream</span></span> structure itself.) We then set <span class="extract"><span class="extract-syntax">stream</span></span> to the <span class="extract"><span class="extract-syntax">continuation</span></span>. Given
that <span class="extract"><span class="extract-syntax">malloc</span></span> was successful &mdash; and it must have been or we would have stopped
with a fatal error &mdash; the continuation is guaranteed to be large enough,
since it's twice the size of the original, which itself was large enough to
hold any escape sequence when opened.
@ -934,11 +934,11 @@ be a little cautious about assuming that a mismatch means an error.
<span class="plain-syntax"> </span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stream_flags</span><span class="plain-syntax"> -= </span><span class="identifier-syntax">B</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stream</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stream_flags</span><span class="plain-syntax"> += </span><span class="identifier-syntax">N</span><span class="plain-syntax">*</span><span class="constant-syntax">INDENTATION_BASE_STRF</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP38"></a><b>&#167;38. </b>We can read the position for any stream, including <code class="display"><span class="extract-syntax">NULL</span></code>, but no matter
how much is written to <code class="display"><span class="extract-syntax">NULL</span></code> this position never budges.
</pre><p class="inwebparagraph"><a id="SP38"></a><b>&#167;38. </b>We can read the position for any stream, including <span class="extract"><span class="extract-syntax">NULL</span></span>, but no matter
how much is written to <span class="extract"><span class="extract-syntax">NULL</span></span> this position never budges.
</p>
<p class="inwebparagraph">Because of continuations, this is not as simple as returning the <code class="display"><span class="extract-syntax">chars_written</span></code>
<p class="inwebparagraph">Because of continuations, this is not as simple as returning the <span class="extract"><span class="extract-syntax">chars_written</span></span>
field.
</p>
@ -1029,8 +1029,8 @@ to open similar ones again).
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP42"></a><b>&#167;42. </b>Lastly, our copying function, where <code class="display"><span class="extract-syntax">from</span></code> has to be a memory stream (or
<code class="display"><span class="extract-syntax">NULL</span></code>) but <code class="display"><span class="extract-syntax">to</span></code> can be anything (including <code class="display"><span class="extract-syntax">NULL</span></code>).
</pre><p class="inwebparagraph"><a id="SP42"></a><b>&#167;42. </b>Lastly, our copying function, where <span class="extract"><span class="extract-syntax">from</span></span> has to be a memory stream (or
<span class="extract"><span class="extract-syntax">NULL</span></span>) but <span class="extract"><span class="extract-syntax">to</span></span> can be anything (including <span class="extract"><span class="extract-syntax">NULL</span></span>).
</p>
<pre class="displayed-code all-displayed-code">
@ -1045,7 +1045,7 @@ to open similar ones again).
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">from</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stream_continues</span><span class="plain-syntax">) </span><a href="2-str.html#SP42" class="function-link"><span class="function-syntax">Streams::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">to</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stream_continues</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP43"></a><b>&#167;43. Writer. </b>This writes one stream into another one, which implements <code class="display"><span class="extract-syntax">%S</span></code>.
</pre><p class="inwebparagraph"><a id="SP43"></a><b>&#167;43. Writer. </b>This writes one stream into another one, which implements <span class="extract"><span class="extract-syntax">%S</span></span>.
</p>
<pre class="displayed-code all-displayed-code">

4
docs/foundation-module/2-trs.html
View file

@ -131,12 +131,12 @@ constraints:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">T</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>Each node in a tree also has a type. Whenever the children of a node change,
they are re-verified by the <code class="display"><span class="extract-syntax">verify_children</span></code>.
they are re-verified by the <span class="extract"><span class="extract-syntax">verify_children</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">tree_node_type</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">node_type_name</span><span class="plain-syntax">; </span><span class="comment"> text such as </span><code class="display"><span class="extract-syntax">I"INVOCATION"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">node_type_name</span><span class="plain-syntax">; </span><span class="comment"> text such as </span><span class="extract"><span class="extract-syntax">I"INVOCATION"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">required_MT</span><span class="plain-syntax">; </span><span class="comment"> if any; or negative for no restriction</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> (*</span><span class="identifier-syntax">verify_children</span><span class="plain-syntax">)(</span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">tree_node</span><span class="plain-syntax"> *); </span><span class="comment"> function to vet the children</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>

40
docs/foundation-module/2-wal.html
View file

@ -47,22 +47,22 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="2-wal.html#SP1">&#167;1. Registration</a></li><li><a href="2-wal.html#SP6">&#167;6. Writing</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Registration. </b>The main function here is modelled on the "minimum <code class="display"><span class="extract-syntax">printf</span></code>" function
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Registration. </b>The main function here is modelled on the "minimum <span class="extract"><span class="extract-syntax">printf</span></span>" function
used as an example in Kernighan and Ritchie, Chapter 7, but because it
prints to streams, it combines the traditional functions <code class="display"><span class="extract-syntax">printf</span></code>, <code class="display"><span class="extract-syntax">sprintf</span></code>
and <code class="display"><span class="extract-syntax">fprintf</span></code> in one. It also contains a number of doohickeys to provide
prints to streams, it combines the traditional functions <span class="extract"><span class="extract-syntax">printf</span></span>, <span class="extract"><span class="extract-syntax">sprintf</span></span>
and <span class="extract"><span class="extract-syntax">fprintf</span></span> in one. It also contains a number of doohickeys to provide
for a wider and extensible range of string interpolations.
</p>
<p class="inwebparagraph">Traditionally, in the C library, everything in the formatting string is
literal except for <code class="display"><span class="extract-syntax">%</span></code> escapes: thus <code class="display"><span class="extract-syntax">%d</span></code> means "integer goes here", and
so on. We follow this but allow extra <code class="display"><span class="extract-syntax">%</span></code> escapes unknown to K&amp;R, and we
also allow a further family of <code class="display"><span class="extract-syntax">$</span></code> escapes intended for the debugging log
literal except for <span class="extract"><span class="extract-syntax">%</span></span> escapes: thus <span class="extract"><span class="extract-syntax">%d</span></span> means "integer goes here", and
so on. We follow this but allow extra <span class="extract"><span class="extract-syntax">%</span></span> escapes unknown to K&amp;R, and we
also allow a further family of <span class="extract"><span class="extract-syntax">$</span></span> escapes intended for the debugging log
only; these are restricted to streams flagged as for debugging and generally
produce guru meditation numbers rather than user-friendly information.
</p>
<p class="inwebparagraph">Each escape, say <code class="display"><span class="extract-syntax">%z</span></code>, must be "registered" before use, and will be
<p class="inwebparagraph">Each escape, say <span class="extract"><span class="extract-syntax">%z</span></span>, must be "registered" before use, and will be
given one of the following categories:
</p>
@ -71,21 +71,21 @@ given one of the following categories:
<span class="definition-keyword">define</span> <span class="constant-syntax">VACANT_ECAT</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax"> </span><span class="comment"> unregistered</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">POINTER_ECAT</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> </span><span class="comment"> data to be printed is a pointer to a structure</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">INTSIZED_ECAT</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="comment"> data to be printed is or fits into an integer</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">WORDING_ECAT</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="comment"> data to be printed is a </span><code class="display"><span class="extract-syntax">wording</span></code><span class="comment"> structure from inform7</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">WORDING_ECAT</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="comment"> data to be printed is a </span><span class="extract"><span class="extract-syntax">wording</span></span><span class="comment"> structure from inform7</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">DIRECT_ECAT</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span><span class="plain-syntax"> </span><span class="comment"> data must be printed directly by the code below</span>
</pre>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>We'll start with <code class="display"><span class="extract-syntax">%</span></code> escapes, which generalise the familiar <code class="display"><span class="extract-syntax">printf</span></code>
escapes such as <code class="display"><span class="extract-syntax">%d</span></code>. Cumbersomely, we need three sorts of escape: those where
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>We'll start with <span class="extract"><span class="extract-syntax">%</span></span> escapes, which generalise the familiar <span class="extract"><span class="extract-syntax">printf</span></span>
escapes such as <span class="extract"><span class="extract-syntax">%d</span></span>. Cumbersomely, we need three sorts of escape: those where
the variable argument token is a pointer, those where it's essentially an
integer, and those where it's a structure used only in the Inform 7 compiler
called a <code class="display"><span class="extract-syntax">wording</span></code>. The standard C typechecker can't generalise across these,
called a <span class="extract"><span class="extract-syntax">wording</span></span>. The standard C typechecker can't generalise across these,
so we have to do everything three times. (And then we have to do all that twice,
because the loggers don't use format strings.)
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">escapes_registered</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">escapes_category</span><span class="plain-syntax">[2][128]; </span><span class="comment"> one of the </span><code class="display"><span class="extract-syntax">*_ECAT</span></code><span class="comment"> values above</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">escapes_category</span><span class="plain-syntax">[2][128]; </span><span class="comment"> one of the </span><span class="extract"><span class="extract-syntax">*_ECAT</span></span><span class="comment"> values above</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">the_escapes</span><span class="plain-syntax">[2][128]; </span><span class="comment"> the function to call to implement this</span>
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> (*</span><span class="identifier-syntax">writer_function</span><span class="plain-syntax">)(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *);</span>
@ -147,11 +147,11 @@ because the loggers don't use format strings.)
<span class="plain-syntax"> </span><span class="identifier-syntax">escapes_category</span><span class="plain-syntax">[</span><span class="identifier-syntax">set</span><span class="plain-syntax">][</span><span class="identifier-syntax">esc</span><span class="plain-syntax">] = </span><span class="identifier-syntax">cat</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">the_escapes</span><span class="plain-syntax">[</span><span class="identifier-syntax">set</span><span class="plain-syntax">][</span><span class="identifier-syntax">esc</span><span class="plain-syntax">] = </span><span class="identifier-syntax">f</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b>We're going to implement <code class="display"><span class="extract-syntax">%d</span></code> and a few others directly, so those are marked
</pre><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b>We're going to implement <span class="extract"><span class="extract-syntax">%d</span></span> and a few others directly, so those are marked
in the table as being unavailable for registration.
</p>
<p class="inwebparagraph">Note that we don't support <code class="display"><span class="extract-syntax">%f</span></code> for floats; but we do add our very own <code class="display"><span class="extract-syntax">%w</span></code>
<p class="inwebparagraph">Note that we don't support <span class="extract"><span class="extract-syntax">%f</span></span> for floats; but we do add our very own <span class="extract"><span class="extract-syntax">%w</span></span>
for wide strings.
</p>
@ -277,19 +277,19 @@ waiting for:
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-wal.html#SP6">&#167;6</a> (twice).</li></ul><p class="inwebparagraph"><a id="SP6_1_1"></a><b>&#167;6.1.1. </b>Here the traditional C library helps us out with the difficult ones to get
right. We don't trouble to check that correct <code class="display"><span class="extract-syntax">printf</span></code> escapes have been used:
right. We don't trouble to check that correct <span class="extract"><span class="extract-syntax">printf</span></span> escapes have been used:
instead, we pass anything in the form of a percentage sign, followed by
up to four nonalphabetic modifying characters, followed by an alphabetic
category character for numerical printing, straight through to <code class="display"><span class="extract-syntax">sprintf</span></code>
or <code class="display"><span class="extract-syntax">fprintf</span></code>.
category character for numerical printing, straight through to <span class="extract"><span class="extract-syntax">sprintf</span></span>
or <span class="extract"><span class="extract-syntax">fprintf</span></span>.
</p>
<p class="inwebparagraph">Thus an escape like <code class="display"><span class="extract-syntax">%04d</span></code> is handled by the standard C library, but not
<code class="display"><span class="extract-syntax">%s</span></code>, which we handle directly. That's for two reasons: first, we want to
<p class="inwebparagraph">Thus an escape like <span class="extract"><span class="extract-syntax">%04d</span></span> is handled by the standard C library, but not
<span class="extract"><span class="extract-syntax">%s</span></span>, which we handle directly. That's for two reasons: first, we want to
be careful to prevent overruns of memory streams; second, we need to ensure
that the correct encoding is used when writing to disc. The numerical
escapes involve only characters whose representation is the same in all our
file encodings, but expanding <code class="display"><span class="extract-syntax">%s</span></code> does not.
file encodings, but expanding <span class="extract"><span class="extract-syntax">%s</span></span> does not.
</p>

54
docs/foundation-module/3-cf.html
View file

@ -48,7 +48,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="3-cf.html#SP3">&#167;3. The routine</a></li><li><a href="3-cf.html#SP3_1">&#167;3.1. Looking for case-insensitive matches instead</a></li><li><a href="3-cf.html#SP3_3">&#167;3.3. Allocation and deallocation</a></li><li><a href="3-cf.html#SP3_6">&#167;3.6. Pathname hacking</a></li><li><a href="3-cf.html#SP4">&#167;4. Counting matches</a></li><li><a href="3-cf.html#SP5">&#167;5. Non-POSIX tail</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This section contains a single utility routine, contributed by Adam
Thornton: a specialised, case-insensitive form of <code class="display"><span class="extract-syntax">fopen()</span></code>. It is specialised
Thornton: a specialised, case-insensitive form of <span class="extract"><span class="extract-syntax">fopen()</span></span>. It is specialised
in that it is designed for opening extensions, where the file path will be
case-correct up to the last two components of the path (the leafname and the
immediately containing directory), but where the casing may be wrong in those
@ -56,32 +56,32 @@ last two components.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>If the exact filename or extension directory (case-correct) exists,
<code class="display"><span class="extract-syntax">CIFilingSystem::fopen()</span></code> will choose it to open. If not, it will
use <code class="display"><span class="extract-syntax">strcasecmp()</span></code> to find a file or directory with the same name but
<span class="extract"><span class="extract-syntax">CIFilingSystem::fopen()</span></span> will choose it to open. If not, it will
use <span class="extract"><span class="extract-syntax">strcasecmp()</span></span> to find a file or directory with the same name but
differing in case and use it instead. If it finds exactly one candidate file,
it will then attempt to <code class="display"><span class="extract-syntax">fopen()</span></code> it and return the result.
it will then attempt to <span class="extract"><span class="extract-syntax">fopen()</span></span> it and return the result.
</p>
<p class="inwebparagraph">If <code class="display"><span class="extract-syntax">CIFilingSystem::fopen()</span></code> succeeds, it returns a <code class="display"><span class="extract-syntax">FILE *</span></code>
(passed back to it from the underlying <code class="display"><span class="extract-syntax">fopen()</span></code>). If
<code class="display"><span class="extract-syntax">CIFilingSystem::fopen()</span></code> fails, it returns <code class="display"><span class="extract-syntax">NULL</span></code>, and
<code class="display"><span class="extract-syntax">errno</span></code> is set accordingly:
<p class="inwebparagraph">If <span class="extract"><span class="extract-syntax">CIFilingSystem::fopen()</span></span> succeeds, it returns a <span class="extract"><span class="extract-syntax">FILE *</span></span>
(passed back to it from the underlying <span class="extract"><span class="extract-syntax">fopen()</span></span>). If
<span class="extract"><span class="extract-syntax">CIFilingSystem::fopen()</span></span> fails, it returns <span class="extract"><span class="extract-syntax">NULL</span></span>, and
<span class="extract"><span class="extract-syntax">errno</span></span> is set accordingly:
</p>
<ul class="items"><li>(a) If no suitable file was found, <code class="display"><span class="extract-syntax">errno</span></code> is set to <code class="display"><span class="extract-syntax">ENOENT</span></code>.
<ul class="items"><li>(a) If no suitable file was found, <span class="extract"><span class="extract-syntax">errno</span></span> is set to <span class="extract"><span class="extract-syntax">ENOENT</span></span>.
</li><li>(b) If more than one possibility was found, but none of them exactly match
the supplied case, <code class="display"><span class="extract-syntax">errno</span></code> is set to <code class="display"><span class="extract-syntax">EBADF</span></code>.
the supplied case, <span class="extract"><span class="extract-syntax">errno</span></span> is set to <span class="extract"><span class="extract-syntax">EBADF</span></span>.
</li><li>(c) Note that if multiple directories which match case-insensitively are
found, but none is an exact match, <code class="display"><span class="extract-syntax">EBADF</span></code> will be set regardless of the
found, but none is an exact match, <span class="extract"><span class="extract-syntax">EBADF</span></span> will be set regardless of the
contents of the directories.
</li><li>(d) If <code class="display"><span class="extract-syntax">CIFilingSystem::fopen()</span></code> fails during its allocation of
</li><li>(d) If <span class="extract"><span class="extract-syntax">CIFilingSystem::fopen()</span></span> fails during its allocation of
space to hold its intermediate strings for comparison, or for its various
data structures, <code class="display"><span class="extract-syntax">errno</span></code> is set to <code class="display"><span class="extract-syntax">ENOMEM</span></code>.
</li><li>(e) If an unambiguous filename is found but the <code class="display"><span class="extract-syntax">fopen()</span></code> fails, <code class="display"><span class="extract-syntax">errno</span></code> is
left at whatever value the underlying <code class="display"><span class="extract-syntax">fopen()</span></code> set it to.
data structures, <span class="extract"><span class="extract-syntax">errno</span></span> is set to <span class="extract"><span class="extract-syntax">ENOMEM</span></span>.
</li><li>(e) If an unambiguous filename is found but the <span class="extract"><span class="extract-syntax">fopen()</span></span> fails, <span class="extract"><span class="extract-syntax">errno</span></span> is
left at whatever value the underlying <span class="extract"><span class="extract-syntax">fopen()</span></span> set it to.
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. The routine. </b>The routine is available only on POSIX platforms where <code class="display"><span class="extract-syntax">PLATFORM_POSIX</span></code>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. The routine. </b>The routine is available only on POSIX platforms where <span class="extract"><span class="extract-syntax">PLATFORM_POSIX</span></span>
is defined (see "Platform-Specific Definitions"). In practice this means
everywhere except Windows, but all Windows file systems are case-preserving
and case-insensitive in any case.
@ -108,7 +108,7 @@ file itself.
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Parse the path to break it into topdir path, extension directory and leafname</span> <span class="named-paragraph-number">3.7</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">topdir</span><span class="plain-syntax"> = </span><span class="identifier-syntax">opendir</span><span class="plain-syntax">(</span><span class="identifier-syntax">topdirpath</span><span class="plain-syntax">); </span><span class="comment"> whose pathname is assumed case-correct...</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">topdir</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="comment"> ...so that failure is fatal; </span><code class="display"><span class="extract-syntax">errno</span></code><span class="comment"> is set by </span><code class="display"><span class="extract-syntax">opendir</span></code>&lt;<span class="named-paragraph">Sad ending to ci-fopen</span> <span class="named-paragraph-number">3.5</span>&gt;<span class="plain-syntax">; </span><span class="comment"> ...so that failure is fatal; </span><code class="display"><span class="extract-syntax">errno</span></code><span class="comment"> is set by </span><code class="display"><span class="extract-syntax">opendir</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">topdir</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="comment"> ...so that failure is fatal; </span><span class="extract"><span class="extract-syntax">errno</span></span><span class="comment"> is set by </span><span class="extract"><span class="extract-syntax">opendir</span></span>&lt;<span class="named-paragraph">Sad ending to ci-fopen</span> <span class="named-paragraph-number">3.5</span>&gt;<span class="plain-syntax">; </span><span class="comment"> ...so that failure is fatal; </span><span class="extract"><span class="extract-syntax">errno</span></span><span class="comment"> is set by </span><span class="extract"><span class="extract-syntax">opendir</span></span>
<span class="plain-syntax"> </span><span class="identifier-syntax">sprintf</span><span class="plain-syntax">(</span><span class="identifier-syntax">workstring</span><span class="plain-syntax">, </span><span class="string-syntax">"%s%c%s"</span><span class="plain-syntax">, </span><span class="identifier-syntax">topdirpath</span><span class="plain-syntax">, </span><span class="constant-syntax">FOLDER_SEPARATOR</span><span class="plain-syntax">, </span><span class="identifier-syntax">ciextdirpath</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">extdir</span><span class="plain-syntax"> = </span><span class="identifier-syntax">opendir</span><span class="plain-syntax">(</span><span class="identifier-syntax">workstring</span><span class="plain-syntax">); </span><span class="comment"> try with supplied extension directory name</span>
@ -201,7 +201,7 @@ return from the function.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Prepare to exit ci-fopen cleanly</span> <span class="named-paragraph-number">3.4.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">handle</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cf.html#SP3">&#167;3</a> (twice), <a href="3-cf.html#SP3_2">&#167;3.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3_5"></a><b>&#167;3.5. </b>...and otherwise <code class="display"><span class="extract-syntax">NULL</span></code>, having already set <code class="display"><span class="extract-syntax">errno</span></code> with the reason why.
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cf.html#SP3">&#167;3</a> (twice), <a href="3-cf.html#SP3_2">&#167;3.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3_5"></a><b>&#167;3.5. </b>...and otherwise <span class="extract"><span class="extract-syntax">NULL</span></span>, having already set <span class="extract"><span class="extract-syntax">errno</span></span> with the reason why.
</p>
@ -242,11 +242,11 @@ return from the function.
<p class="inwebparagraph">into three components:
</p>
</li><li>(a) <code class="display"><span class="extract-syntax">topdirpath</span></code> is <code class="display"><span class="extract-syntax">/Users/bobama/Library/Inform/Extensions</span></code>, and its casing is correct.
</li><li>(b) <code class="display"><span class="extract-syntax">ciextdirpath</span></code> is <code class="display"><span class="extract-syntax">Hillary Clinton</span></code>, but its casing may not be correct.
</li><li>(c) <code class="display"><span class="extract-syntax">ciextname</span></code> is <code class="display"><span class="extract-syntax">Health Care.i7x</span></code>, but its casing may not be correct.
</li><li>(a) <span class="extract"><span class="extract-syntax">topdirpath</span></span> is <span class="extract"><span class="extract-syntax">/Users/bobama/Library/Inform/Extensions</span></span>, and its casing is correct.
</li><li>(b) <span class="extract"><span class="extract-syntax">ciextdirpath</span></span> is <span class="extract"><span class="extract-syntax">Hillary Clinton</span></span>, but its casing may not be correct.
</li><li>(c) <span class="extract"><span class="extract-syntax">ciextname</span></span> is <span class="extract"><span class="extract-syntax">Health Care.i7x</span></span>, but its casing may not be correct.
</li></ul>
<p class="inwebparagraph">The contents of <code class="display"><span class="extract-syntax">workstring</span></code> are not significant afterwards.
<p class="inwebparagraph">The contents of <span class="extract"><span class="extract-syntax">workstring</span></span> are not significant afterwards.
</p>
@ -280,12 +280,12 @@ return from the function.
<span class="plain-syntax"> </span><span class="identifier-syntax">strncpy</span><span class="plain-syntax">(</span><span class="identifier-syntax">ciextdirpath</span><span class="plain-syntax">, </span><span class="identifier-syntax">path</span><span class="plain-syntax"> + </span><span class="identifier-syntax">extdirindex</span><span class="plain-syntax"> + </span><span class="constant-syntax">1</span><span class="plain-syntax">, </span><span class="identifier-syntax">dirlen</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ciextdirpath</span><span class="plain-syntax">[</span><span class="identifier-syntax">dirlen</span><span class="plain-syntax">] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cf.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Counting matches. </b>We count the number of names within the directory which case-insensitively
match against <code class="display"><span class="extract-syntax">name</span></code>, and copy the last which matches into <code class="display"><span class="extract-syntax">last_match</span></code>.
This must be at least as long as <code class="display"><span class="extract-syntax">name</span></code>. (We ought to be just a little careful
match against <span class="extract"><span class="extract-syntax">name</span></span>, and copy the last which matches into <span class="extract"><span class="extract-syntax">last_match</span></span>.
This must be at least as long as <span class="extract"><span class="extract-syntax">name</span></span>. (We ought to be just a little careful
in case of improbable cases where the matched name contains a different
number of characters from <code class="display"><span class="extract-syntax">name</span></code>, for instance because on a strict reading
number of characters from <span class="extract"><span class="extract-syntax">name</span></span>, for instance because on a strict reading
of Unicode "SS" is casing-equivalent to the eszet, but it's unlikely
that many contemporary implementations of <code class="display"><span class="extract-syntax">strcasecmp</span></code> are aware of this,
that many contemporary implementations of <span class="extract"><span class="extract-syntax">strcasecmp</span></span> are aware of this,
and in any case the code above contains much larger buffers than needed.)
</p>
@ -305,7 +305,7 @@ and in any case the code above contains much larger buffers than needed.)
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rc</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Non-POSIX tail. </b>On platforms without POSIX directory handling, we revert to regular <code class="display"><span class="extract-syntax">fopen</span></code>.
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Non-POSIX tail. </b>On platforms without POSIX directory handling, we revert to regular <span class="extract"><span class="extract-syntax">fopen</span></span>.
</p>
<pre class="displayed-code all-displayed-code">

58
docs/foundation-module/3-cla.html
View file

@ -56,9 +56,9 @@ a "bareword". For example, in
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> -log no-memory-usage -fixtime jam marmalade</span>
</pre>
<p class="inwebparagraph">there are two switches, <code class="display"><span class="extract-syntax">-log</span></code> taking an argument (it has valency 2
in the terminology below), <code class="display"><span class="extract-syntax">-fixtime</span></code> not (valency 1). There are
then two barewords, <code class="display"><span class="extract-syntax">jam</span></code> and <code class="display"><span class="extract-syntax">marmalade</span></code>.
<p class="inwebparagraph">there are two switches, <span class="extract"><span class="extract-syntax">-log</span></span> taking an argument (it has valency 2
in the terminology below), <span class="extract"><span class="extract-syntax">-fixtime</span></span> not (valency 1). There are
then two barewords, <span class="extract"><span class="extract-syntax">jam</span></span> and <span class="extract"><span class="extract-syntax">marmalade</span></span>.
</p>
<p class="inwebparagraph">For an example of all this in action, see Inweb, or see the basic
@ -78,7 +78,7 @@ Switches come in five sorts:
<span class="definition-keyword">enum</span> <span class="constant-syntax">TEXTUAL_CLSF</span><span class="plain-syntax"> </span><span class="comment"> sets text to the given value</span>
</pre>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Switches are also grouped, though this affects only the printout of them
in <code class="display"><span class="extract-syntax">-help</span></code>. Groups are enumerated thus:
in <span class="extract"><span class="extract-syntax">-help</span></span>. Groups are enumerated thus:
</p>
@ -89,25 +89,25 @@ in <code class="display"><span class="extract-syntax">-help</span></code>. Group
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">command_line_switch</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">switch_id</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">switch_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">no-verbose</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">switch_sort_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">verbose</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">switch_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">no-verbose</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">switch_sort_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">verbose</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">help_text</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">valency</span><span class="plain-syntax">; </span><span class="comment"> 1 for bare, 2 for one argument follows</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">form</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><code class="display"><span class="extract-syntax">*_CLSF</span></code><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">switch_group</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><code class="display"><span class="extract-syntax">*_CLSG</span></code><span class="comment"> valyes above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">form</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><span class="extract"><span class="extract-syntax">*_CLSF</span></span><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">switch_group</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><span class="extract"><span class="extract-syntax">*_CLSG</span></span><span class="comment"> valyes above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">active_by_default</span><span class="plain-syntax">; </span><span class="comment"> relevant only for booleans</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">command_line_switch</span><span class="plain-syntax"> *</span><span class="identifier-syntax">negates</span><span class="plain-syntax">; </span><span class="comment"> relevant only for booleans</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">command_line_switch</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure command_line_switch is private to this section.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>In case of a prodigious number of switches (ever tried typing <code class="display"><span class="extract-syntax">clang -help</span></code>?),
</pre><ul class="endnotetexts"><li>The structure command_line_switch is private to this section.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>In case of a prodigious number of switches (ever tried typing <span class="extract"><span class="extract-syntax">clang -help</span></span>?),
we'll hash the switch names into the following:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">dictionary</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cls_dictionary</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>The client must declare all the switches her program will make use of, not
counting the standard set already declared by Foundation (such as <code class="display"><span class="extract-syntax">-help</span></code>).
A new <code class="display"><span class="extract-syntax">*_CLSW</span></code> value should be enumerated to be the ID referring to this
counting the standard set already declared by Foundation (such as <span class="extract"><span class="extract-syntax">-help</span></span>).
A new <span class="extract"><span class="extract-syntax">*_CLSW</span></span> value should be enumerated to be the ID referring to this
swtich, and then the client should call:
</p>
@ -150,9 +150,9 @@ swtich, and then the client should call:
<span class="plain-syntax"> </span><a href="2-dct.html#SP8" class="function-link"><span class="function-syntax">Dictionaries::write_value</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cls_dictionary</span><span class="plain-syntax">, </span><span class="identifier-syntax">cls</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">switch_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">cls</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">cls</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b>When we alphabetically sort switches for the <code class="display"><span class="extract-syntax">-help</span></code> output, we want to
file, say, <code class="display"><span class="extract-syntax">-no-verbose</span></code> immediately after <code class="display"><span class="extract-syntax">-verbose</span></code>, not back in the N
section. So the sorting version of <code class="display"><span class="extract-syntax">no-verbose</span></code> is <code class="display"><span class="extract-syntax">verbose_</span></code>.
</pre><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b>When we alphabetically sort switches for the <span class="extract"><span class="extract-syntax">-help</span></span> output, we want to
file, say, <span class="extract"><span class="extract-syntax">-no-verbose</span></span> immediately after <span class="extract"><span class="extract-syntax">-verbose</span></span>, not back in the N
section. So the sorting version of <span class="extract"><span class="extract-syntax">no-verbose</span></span> is <span class="extract"><span class="extract-syntax">verbose_</span></span>.
</p>
@ -166,8 +166,8 @@ section. So the sorting version of <code class="display"><span class="extract-sy
<span class="plain-syntax"> </span><a href="4-sm.html#SP25" class="function-link"><span class="function-syntax">Str::delete_n_characters</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cls</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">switch_sort_name</span><span class="plain-syntax">, </span><span class="constant-syntax">3</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">cls</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">switch_sort_name</span><span class="plain-syntax">, </span><span class="string-syntax">"_"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cla.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Booleans are automatically created in pairs, e.g., <code class="display"><span class="extract-syntax">-destroy-world</span></code> and
<code class="display"><span class="extract-syntax">-no-destroy-world</span></code>:
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cla.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Booleans are automatically created in pairs, e.g., <span class="extract"><span class="extract-syntax">-destroy-world</span></span> and
<span class="extract"><span class="extract-syntax">-no-destroy-world</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -204,16 +204,16 @@ section. So the sorting version of <code class="display"><span class="extract-sy
<span class="plain-syntax"> </span><span class="identifier-syntax">cls</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">form</span><span class="plain-syntax"> = </span><span class="constant-syntax">TEXTUAL_CLSF</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Reading the command line. </b>Once all the switches are declared, the client calls the following routine
in order to parse the usual C <code class="display"><span class="extract-syntax">argc</span></code> and <code class="display"><span class="extract-syntax">argv</span></code> pair, and take action as
appropriate. The client passes a pointer to some structure in <code class="display"><span class="extract-syntax">state</span></code>:
in order to parse the usual C <span class="extract"><span class="extract-syntax">argc</span></span> and <span class="extract"><span class="extract-syntax">argv</span></span> pair, and take action as
appropriate. The client passes a pointer to some structure in <span class="extract"><span class="extract-syntax">state</span></span>:
probably a structure holding its settings variables. When we parse a
switch, we call <code class="display"><span class="extract-syntax">f</span></code> to say so; when we parse a bareword, we call <code class="display"><span class="extract-syntax">g</span></code>. In
each case we pass back <code class="display"><span class="extract-syntax">state</span></code> so that these functions can record whatever
switch, we call <span class="extract"><span class="extract-syntax">f</span></span> to say so; when we parse a bareword, we call <span class="extract"><span class="extract-syntax">g</span></span>. In
each case we pass back <span class="extract"><span class="extract-syntax">state</span></span> so that these functions can record whatever
they would like to in the state structure.
</p>
<p class="inwebparagraph">The return value is <code class="display"><span class="extract-syntax">TRUE</span></code> if the command line appeared to contain at least
one non-trivial request, but <code class="display"><span class="extract-syntax">FALSE</span></code> if it only asked for e.g. <code class="display"><span class="extract-syntax">-help</span></code>. In
<p class="inwebparagraph">The return value is <span class="extract"><span class="extract-syntax">TRUE</span></span> if the command line appeared to contain at least
one non-trivial request, but <span class="extract"><span class="extract-syntax">FALSE</span></span> if it only asked for e.g. <span class="extract"><span class="extract-syntax">-help</span></span>. In
general, the client should then exit with exit code 0 if this happens.
</p>
@ -299,11 +299,11 @@ them back later (i.e., when the debugging log does exist).
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>White space at start and end of lines is ignored; blank lines and those
beginning with a <code class="display"><span class="extract-syntax">#</span></code> are ignored (but a # following other content does not
beginning with a <span class="extract"><span class="extract-syntax">#</span></span> are ignored (but a # following other content does not
mean a comment, so don't use trailing comments on lines); each line must
either be a single switch like <code class="display"><span class="extract-syntax">-no-service</span></code> or a pair like <code class="display"><span class="extract-syntax">-connect tower11</span></code>.
Shell conventions on quoting are not used, but the line <code class="display"><span class="extract-syntax">-greet Fred Smith</span></code>
is equivalent to <code class="display"><span class="extract-syntax">-greet 'Fred Smith'</span></code> on the command line, so there's no
either be a single switch like <span class="extract"><span class="extract-syntax">-no-service</span></span> or a pair like <span class="extract"><span class="extract-syntax">-connect tower11</span></span>.
Shell conventions on quoting are not used, but the line <span class="extract"><span class="extract-syntax">-greet Fred Smith</span></span>
is equivalent to <span class="extract"><span class="extract-syntax">-greet 'Fred Smith'</span></span> on the command line, so there's no
problem with internal space characters in arguments.
</p>
@ -353,7 +353,7 @@ problem with internal space characters in arguments.
<span class="plain-syntax"> (*(</span><span class="identifier-syntax">crs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">g</span><span class="plain-syntax">))(</span><span class="identifier-syntax">crs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">nrt</span><span class="plain-syntax">++, </span><span class="identifier-syntax">opt</span><span class="plain-syntax">, </span><span class="identifier-syntax">crs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">state</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">crs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">subs</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>We also allow <code class="display"><span class="extract-syntax">-setting=X</span></code> as equivalent to <code class="display"><span class="extract-syntax">-setting X</span></code>.
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>We also allow <span class="extract"><span class="extract-syntax">-setting=X</span></span> as equivalent to <span class="extract"><span class="extract-syntax">-setting X</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -407,7 +407,7 @@ problem with internal space characters in arguments.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">cls</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">valency</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP13_1"></a><b>&#167;13.1. </b>The common set of switches declared by Foundation are all handled here;
all other switches are delegated to the client's callback function <code class="display"><span class="extract-syntax">f</span></code>.
all other switches are delegated to the client's callback function <span class="extract"><span class="extract-syntax">f</span></span>.
</p>
@ -467,7 +467,7 @@ all other switches are delegated to the client's callback function <code class="
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="2-dl.html#SP5" class="function-link"><span class="function-syntax">Log::open</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="2-dl.html#SP9" class="function-link"><span class="function-syntax">Log::set_aspect_from_command_line</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cla.html#SP13_1">&#167;13.1</a>.</li></ul><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Help text. </b>That just leaves the following, which implements the <code class="display"><span class="extract-syntax">-help</span></code> switch. It
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-cla.html#SP13_1">&#167;13.1</a>.</li></ul><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Help text. </b>That just leaves the following, which implements the <span class="extract"><span class="extract-syntax">-help</span></span> switch. It
alphabetically sorts the switches, and prints out a list of them as grouped,
with ungrouped switches as the top paragraph and Foundation switches as the
bottom one. (Those are the dull ones.)

4
docs/foundation-module/3-em.html
View file

@ -48,7 +48,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="3-em.html#SP1">&#167;1. Errors handler</a></li><li><a href="3-em.html#SP2">&#167;2. Error messages</a></li><li><a href="3-em.html#SP4">&#167;4. Deliberately crashing</a></li><li><a href="3-em.html#SP5">&#167;5. Survivable errors</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Errors handler. </b>The user can provide a routine to deal with error messages before they're
issued. If this returns <code class="display"><span class="extract-syntax">FALSE</span></code>, nothing is printed to <code class="display"><span class="extract-syntax">stderr</span></code>.
issued. If this returns <span class="extract"><span class="extract-syntax">FALSE</span></span>, nothing is printed to <span class="extract"><span class="extract-syntax">stderr</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -136,7 +136,7 @@ the temporary stream, not some other string which might need fresh allocation.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Deliberately crashing. </b>It's sometimes convenient to get a backtrace from the debugger when an error
occurs unexpectedly, and one way to do that is to force a division by zero.
(This is only enabled by <code class="display"><span class="extract-syntax">-crash</span></code> at the command line and is for debugging only.)
(This is only enabled by <span class="extract"><span class="extract-syntax">-crash</span></span> at the command line and is for debugging only.)
</p>
<pre class="displayed-code all-displayed-code">

8
docs/foundation-module/3-fln.html
View file

@ -172,8 +172,8 @@ as Unicode code points, regardless of what text encoding the locale has.)
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Filename extensions. </b>The following is cautiously written because of an oddity in Windows's handling
of filenames, which are allowed to have trailing dots or spaces, in a way
which isn't necessarily visible to the user, who may have added these by
an accidental brush of the keyboard. Thus <code class="display"><span class="extract-syntax">frog.jpg .</span></code> should be treated
as equivalent to <code class="display"><span class="extract-syntax">frog.jpg</span></code> when deciding the likely file format.
an accidental brush of the keyboard. Thus <span class="extract"><span class="extract-syntax">frog.jpg .</span></span> should be treated
as equivalent to <span class="extract"><span class="extract-syntax">frog.jpg</span></span> when deciding the likely file format.
</p>
<pre class="displayed-code all-displayed-code">
@ -256,10 +256,10 @@ as equivalent to <code class="display"><span class="extract-syntax">frog.jpg</sp
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">NORMALISED</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">verdict</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. Opening. </b>These files are wrappers for <code class="display"><span class="extract-syntax">fopen</span></code>, the traditional C library call, but
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. Opening. </b>These files are wrappers for <span class="extract"><span class="extract-syntax">fopen</span></span>, the traditional C library call, but
referring to the file by filename structure rather than a textual name. Note
that we must transcode the filename to whatever the locale expects before
we call <code class="display"><span class="extract-syntax">fopen</span></code>, which is the main reason for the wrapper.
we call <span class="extract"><span class="extract-syntax">fopen</span></span>, which is the main reason for the wrapper.
</p>
<pre class="displayed-code all-displayed-code">

34
docs/foundation-module/3-pth.html
View file

@ -61,8 +61,8 @@ and "filename" to mean a location of a file. For example:
<span class="plain-syntax"> /Users/rblackmore/Documents/Fireball/whoosh.aiff</span>
</pre>
<p class="inwebparagraph">is a filename. All references to directory locations in the filing system will be
held internally as <code class="display"><span class="extract-syntax">pathname</span></code> objects, and all references to file locations as
<code class="display"><span class="extract-syntax">filename</span></code> objects. Once created, these are never destroyed or modified,
held internally as <span class="extract"><span class="extract-syntax">pathname</span></span> objects, and all references to file locations as
<span class="extract"><span class="extract-syntax">filename</span></span> objects. Once created, these are never destroyed or modified,
so that it's safe to store a pointer to a pathname or filename anywhere.
</p>
@ -76,15 +76,15 @@ describe a directory which doesn't exist on disc.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> /Users/rblackmore/Documents/</span>
</pre>
<p class="inwebparagraph">would be represented as a pointer to the <code class="display"><span class="extract-syntax">pathname</span></code> for "Documents", which
<p class="inwebparagraph">would be represented as a pointer to the <span class="extract"><span class="extract-syntax">pathname</span></span> for "Documents", which
in turn points to one for "rblackmore", which in turn points to "/Users".
Thus the root of the filing system is represented by the null pointer.
</p>
<p class="inwebparagraph">Each <code class="display"><span class="extract-syntax">pathname</span></code> can represent only a single level in the hierarchy, and
its textual name is not allowed to contain the <code class="display"><span class="extract-syntax">FOLDER_SEPARATOR</span></code> character,
with just one exception: the <code class="display"><span class="extract-syntax">pathname</span></code> at the end of the chain is allowed
to begin with <code class="display"><span class="extract-syntax">FOLDER_SEPARATOR</span></code> to denote that it's at the root of the
<p class="inwebparagraph">Each <span class="extract"><span class="extract-syntax">pathname</span></span> can represent only a single level in the hierarchy, and
its textual name is not allowed to contain the <span class="extract"><span class="extract-syntax">FOLDER_SEPARATOR</span></span> character,
with just one exception: the <span class="extract"><span class="extract-syntax">pathname</span></span> at the end of the chain is allowed
to begin with <span class="extract"><span class="extract-syntax">FOLDER_SEPARATOR</span></span> to denote that it's at the root of the
host file system.
</p>
@ -96,7 +96,7 @@ host file system.
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">pathname</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure pathname is accessed in 3/fln and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Home directory. </b>We get the path to the user's home directory from the environment variable
<code class="display"><span class="extract-syntax">HOME</span></code>, if it exists.
<span class="extract"><span class="extract-syntax">HOME</span></span>, if it exists.
</p>
<pre class="displayed-code all-displayed-code">
@ -139,7 +139,7 @@ host file system.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">def</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-pth.html#SP5" class="function-link"><span class="function-syntax">Pathnames::from_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">def</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Creation. </b>A subdirectory is made by taking an existing pathname (or possible <code class="display"><span class="extract-syntax">NULL</span></code>) and
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Creation. </b>A subdirectory is made by taking an existing pathname (or possible <span class="extract"><span class="extract-syntax">NULL</span></span>) and
then going one level deeper, using the supplied name.
</p>
@ -161,9 +161,9 @@ then going one level deeper, using the supplied name.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Text to pathnames. </b>The following takes a text of a name and returns a pathname,
possibly relative to the home directory. Empty directory names are ignored
except possibly for an initial slash, so for example <code class="display"><span class="extract-syntax">paris/roubaix</span></code>,
<code class="display"><span class="extract-syntax">paris//roubaix</span></code> and <code class="display"><span class="extract-syntax">paris/roubaix/</span></code> are indistinguishable here, but
<code class="display"><span class="extract-syntax">/paris/roubaix</span></code> is different.
except possibly for an initial slash, so for example <span class="extract"><span class="extract-syntax">paris/roubaix</span></span>,
<span class="extract"><span class="extract-syntax">paris//roubaix</span></span> and <span class="extract"><span class="extract-syntax">paris/roubaix/</span></span> are indistinguishable here, but
<span class="extract"><span class="extract-syntax">/paris/roubaix</span></span> is different.
</p>
<pre class="displayed-code all-displayed-code">
@ -220,7 +220,7 @@ for example,
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> Fireball/tablature</span>
</pre>
<p class="inwebparagraph">Note that this does not correctly handle symlinks, <code class="display"><span class="extract-syntax">.</span></code>, <code class="display"><span class="extract-syntax">..</span></code> and so on,
<p class="inwebparagraph">Note that this does not correctly handle symlinks, <span class="extract"><span class="extract-syntax">.</span></span>, <span class="extract"><span class="extract-syntax">..</span></span> and so on,
so it's probably not wise to use it with filenames typed in at the command
line.
</p>
@ -249,8 +249,8 @@ line.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">intermediate</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Relative URLs. </b>Suppose a web page in the directory at <code class="display"><span class="extract-syntax">from</span></code> wants to link to a page in
the directory <code class="display"><span class="extract-syntax">to</span></code>. The following composes a minimal-length URL to do so:
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Relative URLs. </b>Suppose a web page in the directory at <span class="extract"><span class="extract-syntax">from</span></span> wants to link to a page in
the directory <span class="extract"><span class="extract-syntax">to</span></span>. The following composes a minimal-length URL to do so:
possibly, if they are in fact the same directory, an empty one.
</p>
@ -302,8 +302,8 @@ on the file system with that path.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">known_to_exist</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. Directory synchronisation. </b>Both pathnames here represent directories which do exist. The function makes
the <code class="display"><span class="extract-syntax">dest</span></code> tree an exact copy of the <code class="display"><span class="extract-syntax">source</span></code> tree (and therefore deletes
anything different which was originally in <code class="display"><span class="extract-syntax">dest</span></code>).
the <span class="extract"><span class="extract-syntax">dest</span></span> tree an exact copy of the <span class="extract"><span class="extract-syntax">source</span></span> tree (and therefore deletes
anything different which was originally in <span class="extract"><span class="extract-syntax">dest</span></span>).
</p>
<pre class="displayed-code all-displayed-code">

8
docs/foundation-module/3-shl.html
View file

@ -49,7 +49,7 @@ function togglePopup(material_id) {
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Operating system interface. </b>Some of our programs have to issue commands to the host operating system,
to copy files, pass them through TeX, and so on. All of that is done using
the C standard library <code class="display"><span class="extract-syntax">system</span></code> function; the commands invoked are all
the C standard library <span class="extract"><span class="extract-syntax">system</span></span> function; the commands invoked are all
standard for POSIX, so will work on MacOS and Linux, but on a Windows system
they would need to be read in a POSIX-style environment like Cygwin.
</p>
@ -87,7 +87,7 @@ they would need to be read in a POSIX-style environment like Cygwin.
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="constant-syntax">SHELL_QUOTE_CHARACTER</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="character-syntax">' '</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The generic shell code to apply <code class="display"><span class="extract-syntax">command</span></code> to a file <code class="display"><span class="extract-syntax">F</span></code>:
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The generic shell code to apply <span class="extract"><span class="extract-syntax">command</span></span> to a file <span class="extract"><span class="extract-syntax">F</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -107,7 +107,7 @@ they would need to be read in a POSIX-style environment like Cygwin.
<span class="plain-syntax"> </span><a href="3-shl.html#SP5" class="function-link"><span class="function-syntax">Shell::run</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">COMMAND</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">COMMAND</span><span class="plain-syntax">)</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Applications to using <code class="display"><span class="extract-syntax">rm</span></code> and <code class="display"><span class="extract-syntax">cp</span></code>:
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Applications to using <span class="extract"><span class="extract-syntax">rm</span></span> and <span class="extract"><span class="extract-syntax">cp</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -126,7 +126,7 @@ they would need to be read in a POSIX-style environment like Cygwin.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">COMMAND</span><span class="plain-syntax">)</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>This writes the traditional Unix shell syntax for redirecting the output
from both <code class="display"><span class="extract-syntax">stdout</span></code> and <code class="display"><span class="extract-syntax">stderr</span></code> to the same named file.
from both <span class="extract"><span class="extract-syntax">stdout</span></span> and <span class="extract"><span class="extract-syntax">stderr</span></span> to the same named file.
</p>
<pre class="displayed-code all-displayed-code">

2
docs/foundation-module/3-tm.html
View file

@ -60,7 +60,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> </span><span class="identifier-syntax">the_present</span><span class="plain-syntax"> = </span><span class="identifier-syntax">localtime</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">right_now</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">fix_time_mode</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The command line option <code class="display"><span class="extract-syntax">-fixtime</span></code> causes any tool compiled with Foundation
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The command line option <span class="extract"><span class="extract-syntax">-fixtime</span></span> causes any tool compiled with Foundation
to fix the date as 11 a.m. on 28 March 2016, which is Inform's birthday. This
makes it easier to automate testing, since we can compare output generated
in one session with output generated another, even though that was on two

12
docs/foundation-module/4-cst.html
View file

@ -45,8 +45,8 @@ function togglePopup(material_id) {
<!--Weave of 'C Strings' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">foundation</a></li><li><a href="index.html#4">Chapter 4: Text Handling</a></li><li><b>C Strings</b></li></ul><p class="purpose">A minimal library for handling C-style strings.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>Programs using Foundation store text in <code class="display"><span class="extract-syntax">text_stream</span></code> structures almost all
of the time, but old-style, null-terminated <code class="display"><span class="extract-syntax">char *</span></code> array strings are
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>Programs using Foundation store text in <span class="extract"><span class="extract-syntax">text_stream</span></span> structures almost all
of the time, but old-style, null-terminated <span class="extract"><span class="extract-syntax">char *</span></span> array strings are
still occasionally needed.
</p>
@ -56,7 +56,7 @@ strings of unlimited length, nor to be parsimonious with memory.
</p>
<p class="inwebparagraph">The following defines a type for a string long enough for our purposes.
It should be at least as long as the constant sometimes called <code class="display"><span class="extract-syntax">PATH_MAX</span></code>,
It should be at least as long as the constant sometimes called <span class="extract"><span class="extract-syntax">PATH_MAX</span></span>,
the maximum length of a pathname, which is 1024 on Mac OS X.
</p>
@ -95,7 +95,7 @@ non-terminated string, though this should never actually happen.
<span class="plain-syntax"> </span><span class="identifier-syntax">str</span><span class="plain-syntax">[</span><span class="constant-syntax">MAX_STRING_LENGTH</span><span class="plain-syntax">] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">MAX_STRING_LENGTH</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>We then have a replacement for <code class="display"><span class="extract-syntax">strcpy</span></code>, identical except that it's
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>We then have a replacement for <span class="extract"><span class="extract-syntax">strcpy</span></span>, identical except that it's
bounds-checked:
</p>
@ -106,7 +106,7 @@ bounds-checked:
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; ((</span><span class="identifier-syntax">from</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">]) &amp;&amp; (</span><span class="identifier-syntax">i</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">MAX_STRING_LENGTH</span><span class="plain-syntax">)); </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) </span><span class="identifier-syntax">to</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">] = </span><span class="identifier-syntax">from</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">];</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">to</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>String comparisons will be done with the following, not <code class="display"><span class="extract-syntax">strcmp</span></code> directly:
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>String comparisons will be done with the following, not <span class="extract"><span class="extract-syntax">strcmp</span></span> directly:
</p>
<pre class="displayed-code all-displayed-code">
@ -143,7 +143,7 @@ whose locale is encoded as UTF-8.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">dest</span><span class="plain-syntax">[</span><span class="identifier-syntax">j</span><span class="plain-syntax">] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>I dislike to use <code class="display"><span class="extract-syntax">strncpy</span></code> because, and for some reason this surprises
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>I dislike to use <span class="extract"><span class="extract-syntax">strncpy</span></span> because, and for some reason this surprises
me every time, it truncates but fails to write a null termination character
if the string to be copied is larger than the buffer to write to: the
result is therefore not a well-formed string and we have to fix matters by

60
docs/foundation-module/4-pm.html
View file

@ -56,7 +56,7 @@ of line terminator will always be stripped out before this is applied.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">c</span><span class="plain-syntax"> == </span><span class="character-syntax">' '</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">c</span><span class="plain-syntax"> == </span><span class="character-syntax">'\t'</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The presence of <code class="display"><span class="extract-syntax">:</span></code> here is perhaps a bit surprising, since it's illegal in
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The presence of <span class="extract"><span class="extract-syntax">:</span></span> here is perhaps a bit surprising, since it's illegal in
C and has other meanings in other languages, but it's legal in C-for-Inform
identifiers.
</p>
@ -70,8 +70,8 @@ identifiers.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Simple parsing. </b>The following finds the earliest minimal-length substring of a string,
delimited by two pairs of characters: for example, <code class="display"><span class="extract-syntax">&lt;&lt;</span></code> and <code class="display"><span class="extract-syntax">&gt;&gt;</span></code>. This could
easily be done as a regular expression using <code class="display"><span class="extract-syntax">Regexp::match</span></code>, but the routine
delimited by two pairs of characters: for example, <span class="extract"><span class="extract-syntax">&lt;&lt;</span></span> and <span class="extract"><span class="extract-syntax">&gt;&gt;</span></span>. This could
easily be done as a regular expression using <span class="extract"><span class="extract-syntax">Regexp::match</span></span>, but the routine
here is much quicker.
</p>
@ -99,7 +99,7 @@ here is much quicker.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> -1;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>Note that we count the empty string as being white space. Again, this is
equivalent to <code class="display"><span class="extract-syntax">Regexp::match(p, " *")</span></code>, but much faster.
equivalent to <span class="extract"><span class="extract-syntax">Regexp::match(p, " *")</span></span>, but much faster.
</p>
<pre class="displayed-code all-displayed-code">
@ -109,8 +109,8 @@ equivalent to <code class="display"><span class="extract-syntax">Regexp::match(p
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. A Worse PCRE. </b>I originally wanted to call the function in this section <code class="display"><span class="extract-syntax">a_better_sscanf</span></code>, then
thought perhaps <code class="display"><span class="extract-syntax">a_worse_PCRE</span></code> would be more true. (PCRE is Philip Hazel's superb
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. A Worse PCRE. </b>I originally wanted to call the function in this section <span class="extract"><span class="extract-syntax">a_better_sscanf</span></span>, then
thought perhaps <span class="extract"><span class="extract-syntax">a_worse_PCRE</span></span> would be more true. (PCRE is Philip Hazel's superb
C implementation of regular-expression parsing, but I didn't need its full strength,
and I didn't want to complicate the build process by linking to it.)
</p>
@ -127,25 +127,25 @@ short texts against particularly simple patterns. Here is an example of use:
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="function-syntax">Regexp::dispose_of</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre>
<p class="inwebparagraph">Note the <code class="display"><span class="extract-syntax">L</span></code> at the front of the regex itself: this is a wide string.
<p class="inwebparagraph">Note the <span class="extract"><span class="extract-syntax">L</span></span> at the front of the regex itself: this is a wide string.
</p>
<p class="inwebparagraph">This tries to match the given <code class="display"><span class="extract-syntax">text</span></code> to see if it consists of the word fish,
<p class="inwebparagraph">This tries to match the given <span class="extract"><span class="extract-syntax">text</span></span> to see if it consists of the word fish,
then any amount of whitespace, then a string of digits which are copied into
<code class="display"><span class="extract-syntax">mr-&gt;exp[0]</span></code>, then whitespace again, and then an alphanumeric identifier to be
copied into <code class="display"><span class="extract-syntax">mr-&gt;exp[1]</span></code>, and finally optional whitespace. (If no match is
<span class="extract"><span class="extract-syntax">mr-&gt;exp[0]</span></span>, then whitespace again, and then an alphanumeric identifier to be
copied into <span class="extract"><span class="extract-syntax">mr-&gt;exp[1]</span></span>, and finally optional whitespace. (If no match is
made, the contents of the found strings are undefined.)
</p>
<p class="inwebparagraph">Note that this differs from, for example, Perl's regular expression matcher
in several ways. The regular expression syntax is slightly different and in
general simpler. A match has to be made from start to end, so it's as if there
were an implicit <code class="display"><span class="extract-syntax">^</span></code> at the front and <code class="display"><span class="extract-syntax">$</span></code> at the back (in Perl terms). The
were an implicit <span class="extract"><span class="extract-syntax">^</span></span> at the front and <span class="extract"><span class="extract-syntax">$</span></span> at the back (in Perl terms). The
full match text is therefore always the entire text put in, so there's no
need to record this. In Perl, matching against <code class="display"><span class="extract-syntax">m/(.*) plus (.*)/</span></code> would
need to record this. In Perl, matching against <span class="extract"><span class="extract-syntax">m/(.*) plus (.*)/</span></span> would
set three subexpressions: number 0 would be the whole text matched, number
1 would be the first bracketed part, number 2 the second. Here, though, the
corresponding regex would be written <code class="display"><span class="extract-syntax">L"(%c*) plus (%c*)"</span></code>, and the bracketed
corresponding regex would be written <span class="extract"><span class="extract-syntax">L"(%c*) plus (%c*)"</span></span>, and the bracketed
terms would be subexpressions 0 and 1.
</p>
@ -268,8 +268,8 @@ deallocate.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">allow_partial</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">[</span><span class="identifier-syntax">at</span><span class="plain-syntax">.</span><span class="element-syntax">ppos</span><span class="plain-syntax">] == </span><span class="constant-syntax">0</span><span class="plain-syntax">)) </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Parentheses in the match pattern set up substrings to extract</span> <span class="named-paragraph-number">11.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chcl</span><span class="plain-syntax">, </span><span class="comment"> what class of characters to match: a </span><code class="display"><span class="extract-syntax">*_CLASS</span></code><span class="comment"> value</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">range_from</span><span class="plain-syntax">, </span><span class="identifier-syntax">range_to</span><span class="plain-syntax">, </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">LITERAL_CLASS</span></code><span class="comment"> only</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chcl</span><span class="plain-syntax">, </span><span class="comment"> what class of characters to match: a </span><span class="extract"><span class="extract-syntax">*_CLASS</span></span><span class="comment"> value</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">range_from</span><span class="plain-syntax">, </span><span class="identifier-syntax">range_to</span><span class="plain-syntax">, </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">LITERAL_CLASS</span></span><span class="comment"> only</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">reverse</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> require a non-match rather than a match</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Extract the character class to match from the pattern</span> <span class="named-paragraph-number">11.2</span>&gt;<span class="plain-syntax">;</span>
@ -281,7 +281,7 @@ deallocate.
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Count how many repetitions can be made here</span> <span class="named-paragraph-number">11.4</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">reps</span><span class="plain-syntax"> &lt; </span><span class="identifier-syntax">rep_from</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> -1;</span>
<span class="plain-syntax"> </span><span class="comment"> we can now accept anything from </span><code class="display"><span class="extract-syntax">rep_from</span></code><span class="comment"> to </span><code class="display"><span class="extract-syntax">reps</span></code><span class="comment"> repetitions</span>
<span class="plain-syntax"> </span><span class="comment"> we can now accept anything from </span><span class="extract"><span class="extract-syntax">rep_from</span></span><span class="comment"> to </span><span class="extract"><span class="extract-syntax">reps</span></span><span class="comment"> repetitions</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">rep_from</span><span class="plain-syntax"> == </span><span class="identifier-syntax">reps</span><span class="plain-syntax">) { </span><span class="identifier-syntax">at</span><span class="plain-syntax">.</span><span class="element-syntax">tpos</span><span class="plain-syntax"> += </span><span class="identifier-syntax">reps</span><span class="plain-syntax">; </span><span class="reserved-syntax">continue</span><span class="plain-syntax">; }</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Try all possible match lengths until we find a match</span> <span class="named-paragraph-number">11.5</span>&gt;<span class="plain-syntax">;</span>
@ -375,25 +375,25 @@ to implement numeric repetition counts, which we won't need:
<span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">no_matched_texts</span><span class="plain-syntax"> = </span><span class="identifier-syntax">at</span><span class="plain-syntax">.</span><span class="element-syntax">bc</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-pm.html#SP11">&#167;11</a>.</li></ul><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>So then: most characters in the pattern are taken literally (if the pattern
says <code class="display"><span class="extract-syntax">q</span></code>, the only match is with a lower-case letter "q"), except that:
says <span class="extract"><span class="extract-syntax">q</span></span>, the only match is with a lower-case letter "q"), except that:
</p>
</li><li>(a) a space means "one or more characters of white space";
</li><li>(b) <code class="display"><span class="extract-syntax">%d</span></code> means any decimal digit;
</li><li>(c) <code class="display"><span class="extract-syntax">%c</span></code> means any character at all;
</li><li>(d) <code class="display"><span class="extract-syntax">%C</span></code> means any character which isn't white space;
</li><li>(e) <code class="display"><span class="extract-syntax">%i</span></code> means any character from the identifier class (see above);
</li><li>(f) <code class="display"><span class="extract-syntax">%p</span></code> means any character which can be used in the name of a Preform
</li><li>(b) <span class="extract"><span class="extract-syntax">%d</span></span> means any decimal digit;
</li><li>(c) <span class="extract"><span class="extract-syntax">%c</span></span> means any character at all;
</li><li>(d) <span class="extract"><span class="extract-syntax">%C</span></span> means any character which isn't white space;
</li><li>(e) <span class="extract"><span class="extract-syntax">%i</span></span> means any character from the identifier class (see above);
</li><li>(f) <span class="extract"><span class="extract-syntax">%p</span></span> means any character which can be used in the name of a Preform
nonterminal, which is to say, an identifier character or a hyphen;
</li><li>(g) <code class="display"><span class="extract-syntax">%P</span></code> means the same or else a colon;
</li><li>(h) <code class="display"><span class="extract-syntax">%t</span></code> means a tab;
</li><li>(i) <code class="display"><span class="extract-syntax">%q</span></code> means a double-quote.
</li><li>(g) <span class="extract"><span class="extract-syntax">%P</span></span> means the same or else a colon;
</li><li>(h) <span class="extract"><span class="extract-syntax">%t</span></span> means a tab;
</li><li>(i) <span class="extract"><span class="extract-syntax">%q</span></span> means a double-quote.
</li></ul>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">%</span></code> otherwise makes a literal escape; a space means any whitespace character;
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">%</span></span> otherwise makes a literal escape; a space means any whitespace character;
square brackets enclose literal alternatives, and note as usual with grep
engines that <code class="display"><span class="extract-syntax">[]xyz]</span></code> is legal and makes a set of four possibilities, the
engines that <span class="extract"><span class="extract-syntax">[]xyz]</span></span> is legal and makes a set of four possibilities, the
first of which is a literal close square; within a set, a hyphen makes a
character range; an initial <code class="display"><span class="extract-syntax">^</span></code> negates the result; and otherwise everything
character range; an initial <span class="extract"><span class="extract-syntax">^</span></span> negates the result; and otherwise everything
is literal.
</p>
@ -475,7 +475,7 @@ is literal.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">match</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Replacement. </b>And this routine conveniently handles searching and replacing. This time we
can match at substrings of the <code class="display"><span class="extract-syntax">text</span></code> (i.e., we are not forced to match
can match at substrings of the <span class="extract"><span class="extract-syntax">text</span></span> (i.e., we are not forced to match
from the start right to the end), and multiple replacements can be made.
For example,
</p>
@ -483,7 +483,7 @@ For example,
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="function-syntax">Regexp::replace</span><span class="plain-syntax">(</span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"[aeiou]"</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"!"</span><span class="plain-syntax">, </span><span class="constant-syntax">REP_REPEATING</span><span class="plain-syntax">);</span>
</pre>
<p class="inwebparagraph">will turn the <code class="display"><span class="extract-syntax">text</span></code> "goose eggs" into "g!!s! !ggs".
<p class="inwebparagraph">will turn the <span class="extract"><span class="extract-syntax">text</span></span> "goose eggs" into "g!!s! !ggs".
</p>

22
docs/foundation-module/4-sm.html
View file

@ -48,8 +48,8 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="4-sm.html#SP1">&#167;1. Strings are streams</a></li><li><a href="4-sm.html#SP2">&#167;2. New strings</a></li><li><a href="4-sm.html#SP4">&#167;4. Converting from C strings</a></li><li><a href="4-sm.html#SP6">&#167;6. Converting to C strings</a></li><li><a href="4-sm.html#SP7">&#167;7. Converting to integers</a></li><li><a href="4-sm.html#SP8">&#167;8. Length</a></li><li><a href="4-sm.html#SP9">&#167;9. Position markers</a></li><li><a href="4-sm.html#SP13">&#167;13. Character operations</a></li><li><a href="4-sm.html#SP15">&#167;15. Truncation</a></li><li><a href="4-sm.html#SP16">&#167;16. Indentation</a></li><li><a href="4-sm.html#SP17">&#167;17. Copying</a></li><li><a href="4-sm.html#SP19">&#167;19. Comparisons</a></li><li><a href="4-sm.html#SP23">&#167;23. White space</a></li><li><a href="4-sm.html#SP25">&#167;25. Deleting characters</a></li><li><a href="4-sm.html#SP26">&#167;26. Substrings</a></li><li><a href="4-sm.html#SP27">&#167;27. Shim for literal storage</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Strings are streams. </b>Although Foundation provides limited facilities for handling standard or
wide C-style strings &mdash; that is, null-terminated arrays of <code class="display"><span class="extract-syntax">char</span></code> or
<code class="display"><span class="extract-syntax">wchar_t</span></code> &mdash; these are not encouraged.
wide C-style strings &mdash; that is, null-terminated arrays of <span class="extract"><span class="extract-syntax">char</span></span> or
<span class="extract"><span class="extract-syntax">wchar_t</span></span> &mdash; these are not encouraged.
</p>
<p class="inwebparagraph">Instead, a standard string for a program using Foundation is nothing more than
@ -73,7 +73,7 @@ duplicating, modifying and examining such strings.
memory to hold it. These objects won't automatically be destroyed, so we
shouldn't call these routines too casually. If we need a string just for
some space to play with for a short while, it's better to create one
with <code class="display"><span class="extract-syntax">TEMPORARY_TEXT</span></code> and then get rid of it with <code class="display"><span class="extract-syntax">DISCARD_TEXT</span></code>, macros
with <span class="extract"><span class="extract-syntax">TEMPORARY_TEXT</span></span> and then get rid of it with <span class="extract"><span class="extract-syntax">DISCARD_TEXT</span></span>, macros
defined in Chapter 2.
</p>
@ -97,8 +97,8 @@ access.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">text</span><span class="plain-syntax">) </span><span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">text</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Duplication of an existing string is complicated only by the issue that
we want the duplicate always to be writeable, so that <code class="display"><span class="extract-syntax">NULL</span></code> can't be
duplicated as <code class="display"><span class="extract-syntax">NULL</span></code>.
we want the duplicate always to be writeable, so that <span class="extract"><span class="extract-syntax">NULL</span></span> can't be
duplicated as <span class="extract"><span class="extract-syntax">NULL</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -183,7 +183,7 @@ thing plus a little extra, for efficiency's sake.
<span class="plain-syntax"> </span><span class="identifier-syntax">buffer</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">atoi</span><span class="plain-syntax">(</span><span class="identifier-syntax">buffer</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Length. </b>A puritan would return a <code class="display"><span class="extract-syntax">size_t</span></code> here, but I am not a puritan.
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Length. </b>A puritan would return a <span class="extract"><span class="extract-syntax">size_t</span></span> here, but I am not a puritan.
</p>
<pre class="displayed-code all-displayed-code">
@ -411,7 +411,7 @@ at those positions may well not be, of course.)
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP20"></a><b>&#167;20. </b>These two routines produce a numerical string difference suitable for
alphabetic sorting, like <code class="display"><span class="extract-syntax">strlen</span></code> in the C standard library.
alphabetic sorting, like <span class="extract"><span class="extract-syntax">strlen</span></span> in the C standard library.
</p>
<pre class="displayed-code all-displayed-code">
@ -435,13 +435,13 @@ alphabetic sorting, like <code class="display"><span class="extract-syntax">strl
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">S1</span><span class="plain-syntax">) - </span><a href="4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">S2</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP21"></a><b>&#167;21. </b>It's sometimes useful to see whether two strings agree on their last
<code class="display"><span class="extract-syntax">N</span></code> characters, or their first <code class="display"><span class="extract-syntax">N</span></code>. For example,
<span class="extract"><span class="extract-syntax">N</span></span> characters, or their first <span class="extract"><span class="extract-syntax">N</span></span>. For example,
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="function-syntax">Str::suffix_eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"wayzgoose"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"snow goose"</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">)</span>
</pre>
<p class="inwebparagraph">will return <code class="display"><span class="extract-syntax">TRUE</span></code> for <code class="display"><span class="extract-syntax">N</span></code> equal to 0 to 5, and <code class="display"><span class="extract-syntax">FALSE</span></code> thereafter.
<p class="inwebparagraph">will return <span class="extract"><span class="extract-syntax">TRUE</span></span> for <span class="extract"><span class="extract-syntax">N</span></span> equal to 0 to 5, and <span class="extract"><span class="extract-syntax">FALSE</span></span> thereafter.
</p>
<p class="inwebparagraph">(The Oxford English Dictionary defines a "wayzgoose" as a holiday outing
@ -659,8 +659,8 @@ for the staff of a publishing house.)
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. Shim for literal storage. </b>This is where all of those I-literals created by Inweb are stored at run-time.
Note that every instance of, say, <code class="display"><span class="extract-syntax">I"fish"</span></code> would return the same string,
that is, the same <code class="display"><span class="extract-syntax">text_stream *</span></code> value. To prevent nasty accidents, this
Note that every instance of, say, <span class="extract"><span class="extract-syntax">I"fish"</span></span> would return the same string,
that is, the same <span class="extract"><span class="extract-syntax">text_stream *</span></span> value. To prevent nasty accidents, this
is marked so that the stream value, "fish", cannot be modified at run-time.
</p>

34
docs/foundation-module/4-taa.html
View file

@ -62,13 +62,13 @@ There are two versions of this: a start head represents matching from the
front of a text, whereas an end head represents matching from the back.
</li><li>(b) "Choices". A choice node has a given match character, say an "f", and
represents which node to go to next if this is the current character in the
text. It must either be a valid Unicode character or <code class="display"><span class="extract-syntax">TRIE_ANYTHING</span></code>, which
text. It must either be a valid Unicode character or <span class="extract"><span class="extract-syntax">TRIE_ANYTHING</span></span>, which
is a wildcard representing "any text of any length here". Since a choice
must always lead somewhere, <code class="display"><span class="extract-syntax">on_success</span></code> must point to another node.
must always lead somewhere, <span class="extract"><span class="extract-syntax">on_success</span></span> must point to another node.
There can be any number of choices at a given position, so choice nodes
are always organised in linked lists joined by <code class="display"><span class="extract-syntax">next</span></code>.
are always organised in linked lists joined by <span class="extract"><span class="extract-syntax">next</span></span>.
</li><li>(c) "Terminals", always leaves, which have match character set to the
impossible value <code class="display"><span class="extract-syntax">TRIE_STOP</span></code>, and for which <code class="display"><span class="extract-syntax">match_outcome</span></code> is non-null; thus,
impossible value <span class="extract"><span class="extract-syntax">TRIE_STOP</span></span>, and for which <span class="extract"><span class="extract-syntax">match_outcome</span></span> is non-null; thus,
different terminal nodes can result in different outcomes if they are ever
reached at the end of a successful scan. A terminal node is always the only item
in a list.
@ -93,30 +93,30 @@ in a list.
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">match_trie</span><span class="plain-syntax"> *</span><span class="identifier-syntax">next</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">match_trie</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure match_trie is accessed in 2/mmr, 2/trs and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>We have just one routine for extending and scanning the trie: it either
tries to find whether a text <code class="display"><span class="extract-syntax">p</span></code> leads to any outcome in the existing trie,
tries to find whether a text <span class="extract"><span class="extract-syntax">p</span></span> leads to any outcome in the existing trie,
or else forcibly extends the existing trie to ensure that it does.
</p>
<p class="inwebparagraph">It might look as if calling <code class="display"><span class="extract-syntax">Tries::search</span></code> always returns <code class="display"><span class="extract-syntax">add_outcome</span></code> when
<p class="inwebparagraph">It might look as if calling <span class="extract"><span class="extract-syntax">Tries::search</span></span> always returns <span class="extract"><span class="extract-syntax">add_outcome</span></span> when
this is set, but this isn't true: if the trie already contains a node
representing how to deal with <code class="display"><span class="extract-syntax">p</span></code>, we get whatever outcome is already
representing how to deal with <span class="extract"><span class="extract-syntax">p</span></span>, we get whatever outcome is already
established.
</p>
<p class="inwebparagraph">There are two motions to keep track of: our progress through the text <code class="display"><span class="extract-syntax">p</span></code>
<p class="inwebparagraph">There are two motions to keep track of: our progress through the text <span class="extract"><span class="extract-syntax">p</span></span>
being scanned, and our progress through the trie which tells us how to scan it.
</p>
<p class="inwebparagraph">We scan the text either forwards or backwards, starting with the first or
last character and then working through, finishing with a 0 terminator.
(This is true even if working backwards: we pretend the character stored
before the text began is 0.) <code class="display"><span class="extract-syntax">i</span></code> represents the index of our current position
in <code class="display"><span class="extract-syntax">p</span></code>, and runs either from 0 up to <code class="display"><span class="extract-syntax">N</span></code> or from <code class="display"><span class="extract-syntax">N-1</span></code> down to <code class="display"><span class="extract-syntax">-1</span></code>,
where <code class="display"><span class="extract-syntax">N</span></code> is the number of characters in <code class="display"><span class="extract-syntax">p</span></code>.
before the text began is 0.) <span class="extract"><span class="extract-syntax">i</span></span> represents the index of our current position
in <span class="extract"><span class="extract-syntax">p</span></span>, and runs either from 0 up to <span class="extract"><span class="extract-syntax">N</span></span> or from <span class="extract"><span class="extract-syntax">N-1</span></span> down to <span class="extract"><span class="extract-syntax">-1</span></span>,
where <span class="extract"><span class="extract-syntax">N</span></span> is the number of characters in <span class="extract"><span class="extract-syntax">p</span></span>.
</p>
<p class="inwebparagraph">We scan the trie using a pair of pointers. <code class="display"><span class="extract-syntax">prev</span></code> is the last node we
successfully left, and <code class="display"><span class="extract-syntax">pos</span></code> is one we are currently at, which can be
<p class="inwebparagraph">We scan the trie using a pair of pointers. <span class="extract"><span class="extract-syntax">prev</span></span> is the last node we
successfully left, and <span class="extract"><span class="extract-syntax">pos</span></span> is one we are currently at, which can be
either a terminal node or a choice node (in which case it's the head of
a linked list of such nodes).
</p>
@ -201,8 +201,8 @@ But we aren't going to search these tries anything like intensively enough
to make it worth the trouble.
</p>
<p class="inwebparagraph">(The following cannot be a <code class="display"><span class="extract-syntax">while</span></code> loop since C does not allow us to <code class="display"><span class="extract-syntax">break</span></code>
or <code class="display"><span class="extract-syntax">continue</span></code> out of an outer loop from an inner one.)
<p class="inwebparagraph">(The following cannot be a <span class="extract"><span class="extract-syntax">while</span></span> loop since C does not allow us to <span class="extract"><span class="extract-syntax">break</span></span>
or <span class="extract"><span class="extract-syntax">continue</span></span> out of an outer loop from an inner one.)
</p>
@ -283,8 +283,8 @@ or <code class="display"><span class="extract-syntax">continue</span></code> out
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">pos</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"trie invariant broken"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">prev</span><span class="plain-syntax"> = </span><span class="identifier-syntax">pos</span><span class="plain-syntax">; </span><span class="identifier-syntax">pos</span><span class="plain-syntax"> = </span><span class="identifier-syntax">prev</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_success</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-taa.html#SP2">&#167;2</a> (twice), <a href="4-taa.html#SP2_2">&#167;2.2</a>, <a href="4-taa.html#SP2_3">&#167;2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP2_5"></a><b>&#167;2.5. </b>If <code class="display"><span class="extract-syntax">pos</span></code> is <code class="display"><span class="extract-syntax">NULL</span></code> then it follows that <code class="display"><span class="extract-syntax">prev-&gt;on_success</span></code> is <code class="display"><span class="extract-syntax">NULL</span></code>, since
this is how <code class="display"><span class="extract-syntax">pos</span></code> was calculated; so to add a new terminal node we simply add
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-taa.html#SP2">&#167;2</a> (twice), <a href="4-taa.html#SP2_2">&#167;2.2</a>, <a href="4-taa.html#SP2_3">&#167;2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP2_5"></a><b>&#167;2.5. </b>If <span class="extract"><span class="extract-syntax">pos</span></span> is <span class="extract"><span class="extract-syntax">NULL</span></span> then it follows that <span class="extract"><span class="extract-syntax">prev-&gt;on_success</span></span> is <span class="extract"><span class="extract-syntax">NULL</span></span>, since
this is how <span class="extract"><span class="extract-syntax">pos</span></span> was calculated; so to add a new terminal node we simply add
it there.
</p>

34
docs/foundation-module/4-tf.html
View file

@ -106,8 +106,8 @@ file actually exists on disc at a given filename:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Text file scanner. </b>We read lines in, delimited by any of the standard line-ending characters,
and send them one at a time to a function called <code class="display"><span class="extract-syntax">iterator</span></code>. Throughout,
we preserve a pointer called <code class="display"><span class="extract-syntax">state</span></code> to some object being used by the
and send them one at a time to a function called <span class="extract"><span class="extract-syntax">iterator</span></span>. Throughout,
we preserve a pointer called <span class="extract"><span class="extract-syntax">state</span></span> to some object being used by the
client.
</p>
@ -134,10 +134,10 @@ client.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">serious</span><span class="plain-syntax">) </span><a href="3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">message</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> { </span><a href="3-em.html#SP7" class="function-link"><span class="function-syntax">Errors::with_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">message</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">; }</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-tf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_2"></a><b>&#167;5.2. </b>The ANSI definition of <code class="display"><span class="extract-syntax">ftell</span></code> and <code class="display"><span class="extract-syntax">fseek</span></code> says that, with text files, the
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-tf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_2"></a><b>&#167;5.2. </b>The ANSI definition of <span class="extract"><span class="extract-syntax">ftell</span></span> and <span class="extract"><span class="extract-syntax">fseek</span></span> says that, with text files, the
only definite position value is 0 &mdash; meaning the beginning of the file &mdash; and
this is what we initialise <code class="display"><span class="extract-syntax">line_position</span></code> to. We must otherwise only write
values returned by <code class="display"><span class="extract-syntax">ftell</span></code> into this field.
this is what we initialise <span class="extract"><span class="extract-syntax">line_position</span></span> to. We must otherwise only write
values returned by <span class="extract"><span class="extract-syntax">ftell</span></span> into this field.
</p>
@ -160,8 +160,8 @@ values returned by <code class="display"><span class="extract-syntax">ftell</spa
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">.</span><span class="element-syntax">actively_scanning</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">.</span><span class="element-syntax">text_file_filename</span><span class="plain-syntax"> = </span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-tf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_3"></a><b>&#167;5.3. </b>We aim to get this right whether the lines are terminated by <code class="display"><span class="extract-syntax">0A</span></code>, <code class="display"><span class="extract-syntax">0D</span></code>,
<code class="display"><span class="extract-syntax">0A 0D</span></code> or <code class="display"><span class="extract-syntax">0D 0A</span></code>. The final line is not required to be terminated.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-tf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_3"></a><b>&#167;5.3. </b>We aim to get this right whether the lines are terminated by <span class="extract"><span class="extract-syntax">0A</span></span>, <span class="extract"><span class="extract-syntax">0D</span></span>,
<span class="extract"><span class="extract-syntax">0A 0D</span></span> or <span class="extract"><span class="extract-syntax">0D 0A</span></span>. The final line is not required to be terminated.
</p>
@ -203,12 +203,12 @@ values returned by <code class="display"><span class="extract-syntax">ftell</spa
<span class="plain-syntax"> </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">.</span><span class="element-syntax">line_count</span><span class="plain-syntax">++;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-tf.html#SP5_3">&#167;5.3</a> (twice).</li></ul><p class="inwebparagraph"><a id="SP5_3_2"></a><b>&#167;5.3.2. </b>But we update the text file position after every apparent line terminator.
This is because we might otherwise, on a Windows text file, end up with an
<code class="display"><span class="extract-syntax">ftell</span></code> position in between the <code class="display"><span class="extract-syntax">CR</span></code> and the <code class="display"><span class="extract-syntax">LF</span></code>; if we resume at that point,
<span class="extract"><span class="extract-syntax">ftell</span></span> position in between the <span class="extract"><span class="extract-syntax">CR</span></span> and the <span class="extract"><span class="extract-syntax">LF</span></span>; if we resume at that point,
later on, we'll then have an off-by-one error in the line numbering in the
resumption as compared to during the original pass.
</p>
<p class="inwebparagraph">Properly speaking, <code class="display"><span class="extract-syntax">ftell</span></code> returns a long <code class="display"><span class="extract-syntax">int</span></code>, not an <code class="display"><span class="extract-syntax">int</span></code>, but on a
<p class="inwebparagraph">Properly speaking, <span class="extract"><span class="extract-syntax">ftell</span></span> returns a long <span class="extract"><span class="extract-syntax">int</span></span>, not an <span class="extract"><span class="extract-syntax">int</span></span>, but on a
32-bit-or-more integer machine, this gives us room for files to run to 2GB.
Text files seldom come that large.
</p>
@ -259,10 +259,10 @@ calling the following:
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Reading UTF-8 files. </b>The following routine reads a sequence of Unicode characters from a UTF-8
encoded file, but returns them as a sequence of ISO Latin-1 characters, a
trick it can only pull off by escaping non-ISO characters. This is done by
taking character number <code class="display"><span class="extract-syntax">N</span></code> and feeding it out, one character at a time, as
the text <code class="display"><span class="extract-syntax">[unicode N]</span></code>, writing the number in decimal. Only one UTF-8
taking character number <span class="extract"><span class="extract-syntax">N</span></span> and feeding it out, one character at a time, as
the text <span class="extract"><span class="extract-syntax">[unicode N]</span></span>, writing the number in decimal. Only one UTF-8
file like this will be being read at a time, and the routine will be
repeatedly called until <code class="display"><span class="extract-syntax">EOF</span></code> or a line division.
repeatedly called until <span class="extract"><span class="extract-syntax">EOF</span></span> or a line division.
</p>
<p class="inwebparagraph">Strictly speaking, we transmit not as ISO Latin-1 but as that subset of ISO
@ -271,13 +271,13 @@ excludes some typewriter symbols and a handful of letterforms, as we shall
see.
</p>
<p class="inwebparagraph">There are two exceptions: <code class="display"><span class="extract-syntax">TextFiles::utf8_fgetc</span></code> can also return the usual C
end-of-file pseudo-character <code class="display"><span class="extract-syntax">EOF</span></code>, and it can also return the Unicode BOM
<p class="inwebparagraph">There are two exceptions: <span class="extract"><span class="extract-syntax">TextFiles::utf8_fgetc</span></span> can also return the usual C
end-of-file pseudo-character <span class="extract"><span class="extract-syntax">EOF</span></span>, and it can also return the Unicode BOM
(byte-ordering marker) pseudo-character, which is legal at the start of a
file and which is automatically prepended by some text editors and
word-processors when they save a UTF-8 file (though in fact it is not
required by the UTF-8 specification). Anyone calling <code class="display"><span class="extract-syntax">TextFiles::utf8_fgetc</span></code> must
check the return value for <code class="display"><span class="extract-syntax">EOF</span></code> every time, and for <code class="display"><span class="extract-syntax">0xFEFF</span></code> every time we
required by the UTF-8 specification). Anyone calling <span class="extract"><span class="extract-syntax">TextFiles::utf8_fgetc</span></span> must
check the return value for <span class="extract"><span class="extract-syntax">EOF</span></span> every time, and for <span class="extract"><span class="extract-syntax">0xFEFF</span></span> every time we
might be at the start of the file being read.
</p>
@ -355,7 +355,7 @@ rather than Douglas Adams, they might have filled this gap. As it was,
"eth" never occurred in any of their works.)
</p>
<p class="inwebparagraph">We let the multiplication sign <code class="display"><span class="extract-syntax">0xd7</span></code> through even though ZSCII doesn't
<p class="inwebparagraph">We let the multiplication sign <span class="extract"><span class="extract-syntax">0xd7</span></span> through even though ZSCII doesn't
support it, but convert it to an "x": this is so that we can parse numbers
in scientific notation.
</p>

4
docs/foundation-module/4-ws.html
View file

@ -45,8 +45,8 @@ function togglePopup(material_id) {
<!--Weave of 'Wide Strings' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">foundation</a></li><li><a href="index.html#4">Chapter 4: Text Handling</a></li><li><b>Wide Strings</b></li></ul><p class="purpose">A minimal library for handling wide C strings.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>By "wide string", we mean an array of <code class="display"><span class="extract-syntax">wchar_t</span></code>. A pointer to this type
is what is returned by an L-literal in ANSI C, such as <code class="display"><span class="extract-syntax">L"look, I'm wide"</span></code>.
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>By "wide string", we mean an array of <span class="extract"><span class="extract-syntax">wchar_t</span></span>. A pointer to this type
is what is returned by an L-literal in ANSI C, such as <span class="extract"><span class="extract-syntax">L"look, I'm wide"</span></span>.
A wide string is essentially a C string but with characters stored in full
words instead of bytes. The character values should be Unicode code points.
</p>

16
docs/foundation-module/5-ee.html
View file

@ -68,22 +68,22 @@ essentially individual HTML files, plus some images.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">ebook</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">metadata_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">ebook_datum</span></code><span class="comment">: DCMI-standard bibliographic data</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">metadata_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">ebook_datum</span></span><span class="comment">: DCMI-standard bibliographic data</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prefix</span><span class="plain-syntax">; </span><span class="comment"> to apply to the page leafnames</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CSS_file_throughout</span><span class="plain-syntax">; </span><span class="comment"> where to find a CSS file to be used for all volumes</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">eventual_epub</span><span class="plain-syntax">; </span><span class="comment"> filename of the final </span><code class="display"><span class="extract-syntax">*.epub</span></code><span class="comment"> to be made</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">eventual_epub</span><span class="plain-syntax">; </span><span class="comment"> filename of the final </span><span class="extract"><span class="extract-syntax">*.epub</span></span><span class="comment"> to be made</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">holder</span><span class="plain-syntax">; </span><span class="comment"> directory to put the ingredients into</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OEBPS_path</span><span class="plain-syntax">; </span><span class="comment"> subdirectory which mysteriously has to be called </span><code class="display"><span class="extract-syntax">OEBPS</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OEBPS_path</span><span class="plain-syntax">; </span><span class="comment"> subdirectory which mysteriously has to be called </span><span class="extract"><span class="extract-syntax">OEBPS</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_volume_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">ebook_volume</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_volume_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">ebook_volume</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">ebook_volume</span><span class="plain-syntax"> *</span><span class="identifier-syntax">current_volume</span><span class="plain-syntax">; </span><span class="comment"> the one to which chapters are now being added</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_chapter_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">ebook_chapter</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_chapter_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">ebook_chapter</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">ebook_chapter</span><span class="plain-syntax"> *</span><span class="identifier-syntax">current_chapter</span><span class="plain-syntax">; </span><span class="comment"> the one to which pages are now being added</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_page_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">book_page</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_image_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">ebook_image</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_page_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">book_page</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_image_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">ebook_image</span></span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">ebook</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure ebook is private to this section.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>DCMI, or "Dublin Core", metadata is a standard set of key-value pairs used to
@ -112,7 +112,7 @@ list is entirely sufficient.
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapter_title</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">ebook_volume</span><span class="plain-syntax"> *</span><span class="identifier-syntax">in_volume</span><span class="plain-syntax">; </span><span class="comment"> to which volume this chapter belongs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">ebook_page</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapter_starts</span><span class="plain-syntax">; </span><span class="comment"> on which page the chapter starts</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_mark_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">ebook_mark</span></code><span class="comment">: for when multiple navigable points exist within this</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ebook_mark_list</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">ebook_mark</span></span><span class="comment">: for when multiple navigable points exist within this</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">start_URL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">ebook_chapter</span><span class="plain-syntax">;</span>

8
docs/foundation-module/5-htm.html
View file

@ -50,8 +50,8 @@ function togglePopup(material_id) {
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Abstraction. </b>Though the code below does nothing at all interesting, to put it mildly,
it's written a little defensively, to increase the chances that the client
is producing valid HTML with it. In particular, the client won't be
allowed to open a <code class="display"><span class="extract-syntax">p</span></code> tag, then open a <code class="display"><span class="extract-syntax">b</span></code> tag, then close the <code class="display"><span class="extract-syntax">p</span></code>, then
close the <code class="display"><span class="extract-syntax">b</span></code>: that would be wrongly nested. We want to throw errors like
allowed to open a <span class="extract"><span class="extract-syntax">p</span></span> tag, then open a <span class="extract"><span class="extract-syntax">b</span></span> tag, then close the <span class="extract"><span class="extract-syntax">p</span></span>, then
close the <span class="extract"><span class="extract-syntax">b</span></span>: that would be wrongly nested. We want to throw errors like
that into the debugging log, so:
</p>
@ -60,14 +60,14 @@ that into the debugging log, so:
<span class="definition-keyword">define</span> <span class="identifier-syntax">tag_error</span><span class="plain-syntax">(</span><span class="identifier-syntax">x</span><span class="plain-syntax">) { </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Tag error: %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">x</span><span class="plain-syntax">); }</span>
</pre>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Any text stream can be declared as being HTML, and therefore subject to
this auditing. To do that, we atach an <code class="display"><span class="extract-syntax">HTML_file_state</span></code> object to the
this auditing. To do that, we atach an <span class="extract"><span class="extract-syntax">HTML_file_state</span></span> object to the
text stream.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">HTML_file_state</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">XHTML_flag</span><span class="plain-syntax">; </span><span class="comment"> writing strict XHTML for use in epubs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="constant-syntax">lifo_stack</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tag_stack</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">HTML_tag</span></code><span class="comment">: those currently open</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="constant-syntax">lifo_stack</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tag_stack</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">HTML_tag</span></span><span class="comment">: those currently open</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">CSS_included</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">JS_included</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>

4
docs/foundation-module/6-bf.html
View file

@ -193,8 +193,8 @@ floating-point numbers:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>And lastly we read a string of a supplied length from the file, and
then null terminate it to make it valid C string. (<code class="display"><span class="extract-syntax">string</span></code> must therefore
be at least <code class="display"><span class="extract-syntax">length</span></code> plus 1 bytes long.)
then null terminate it to make it valid C string. (<span class="extract"><span class="extract-syntax">string</span></span> must therefore
be at least <span class="extract"><span class="extract-syntax">length</span></span> plus 1 bytes long.)
</p>
<pre class="displayed-code all-displayed-code">

16
docs/foundation-module/6-id.html
View file

@ -48,8 +48,8 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="6-id.html#SP1">&#167;1. JPEG files</a></li><li><a href="6-id.html#SP2">&#167;2. PNG files</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. JPEG files. </b>The following code, contributed by Toby Nelson, either finds the pixel width
and height of a given JPEG file and returns <code class="display"><span class="extract-syntax">TRUE</span></code> or, if it can't read the
file or doesn't recognise the header as having JPEG format, returns <code class="display"><span class="extract-syntax">FALSE</span></code>.
and height of a given JPEG file and returns <span class="extract"><span class="extract-syntax">TRUE</span></span> or, if it can't read the
file or doesn't recognise the header as having JPEG format, returns <span class="extract"><span class="extract-syntax">FALSE</span></span>.
</p>
<p class="inwebparagraph">JPEG is properly speaking not a file format but a compression technique:
@ -58,8 +58,8 @@ simpler cousin JFIF (JPEG File Interchange Format).
</p>
<p class="inwebparagraph">We scan the file looking for "markers", each of which begins with an
<code class="display"><span class="extract-syntax">0xFF</span></code> byte and is followed by a marker-type byte which is neither <code class="display"><span class="extract-syntax">0x00</span></code>
nor <code class="display"><span class="extract-syntax">0xFF</span></code>. The compulsory marker SOI must appear at the start of the file,
<span class="extract"><span class="extract-syntax">0xFF</span></span> byte and is followed by a marker-type byte which is neither <span class="extract"><span class="extract-syntax">0x00</span></span>
nor <span class="extract"><span class="extract-syntax">0xFF</span></span>. The compulsory marker SOI must appear at the start of the file,
providing one way to detect probable JPEGs by looking at the first two
bytes. There must also eventually be a start of frame marker, for the
actual image: this can have many forms, but in all cases tells us the
@ -72,22 +72,22 @@ height and width.
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">marker</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int16</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">JPEG_file</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0xFFD8</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">0xFF</span></code><span class="comment"> (marker) then </span><code class="display"><span class="extract-syntax">0xD8</span></code><span class="comment"> (SOI)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0xFFD8</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">0xFF</span></span><span class="comment"> (marker) then </span><span class="extract"><span class="extract-syntax">0xD8</span></span><span class="comment"> (SOI)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">do</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">do</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">marker</span><span class="plain-syntax"> = </span><span class="identifier-syntax">getc</span><span class="plain-syntax">(</span><span class="identifier-syntax">JPEG_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">marker</span><span class="plain-syntax"> == </span><span class="identifier-syntax">EOF</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">marker</span><span class="plain-syntax"> != </span><span class="constant-syntax">0xff</span><span class="plain-syntax">); </span><span class="comment"> skip to next </span><code class="display"><span class="extract-syntax">0xFF</span></code><span class="comment"> byte</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">marker</span><span class="plain-syntax"> != </span><span class="constant-syntax">0xff</span><span class="plain-syntax">); </span><span class="comment"> skip to next </span><span class="extract"><span class="extract-syntax">0xFF</span></span><span class="comment"> byte</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">do</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">marker</span><span class="plain-syntax"> = </span><span class="identifier-syntax">getc</span><span class="plain-syntax">(</span><span class="identifier-syntax">JPEG_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">marker</span><span class="plain-syntax"> == </span><span class="constant-syntax">0xff</span><span class="plain-syntax">); </span><span class="comment"> skip to next non </span><code class="display"><span class="extract-syntax">FF</span></code><span class="comment"> byte</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">marker</span><span class="plain-syntax"> == </span><span class="constant-syntax">0xff</span><span class="plain-syntax">); </span><span class="comment"> skip to next non </span><span class="extract"><span class="extract-syntax">FF</span></span><span class="comment"> byte</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int16</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">JPEG_file</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">length</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> length of marker</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax">(</span><span class="identifier-syntax">marker</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="comment"> all variant forms of "start of frame": e.g., </span><code class="display"><span class="extract-syntax">0xC0</span></code><span class="comment"> is a baseline DCT image</span>
<span class="plain-syntax"> </span><span class="comment"> all variant forms of "start of frame": e.g., </span><span class="extract"><span class="extract-syntax">0xC0</span></span><span class="comment"> is a baseline DCT image</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc0</span><span class="identifier-syntax">:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc1</span><span class="identifier-syntax">:</span><span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc2</span><span class="identifier-syntax">:</span><span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc3</span><span class="identifier-syntax">:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc5</span><span class="identifier-syntax">:</span><span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc6</span><span class="identifier-syntax">:</span><span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">0xc7</span><span class="identifier-syntax">:</span>

24
docs/foundation-module/6-sd.html
View file

@ -62,19 +62,19 @@ Durations are measured in centiseconds.
<span class="plain-syntax"> </span><span class="reserved-syntax">unsigned</span><span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sampleSize</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x464F524D</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"FORM"</span></code><span class="comment"> indicating an IFF file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x464F524D</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"FORM"</span></span><span class="comment"> indicating an IFF file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x41494646</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"AIFF"</span></code><span class="comment"> indicating an AIFF file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x41494646</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"AIFF"</span></span><span class="comment"> indicating an AIFF file</span>
<span class="plain-syntax"> </span><span class="comment"> Read chunks, skipping over those we are not interested in</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="constant-syntax">TRUE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">chunkID</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">chunkLength</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">chunkID</span><span class="plain-syntax"> == </span><span class="constant-syntax">0x434F4D4D</span><span class="plain-syntax">) { </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"COMM"</span></code><span class="comment"> indicates common AIFF data</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">chunkID</span><span class="plain-syntax"> == </span><span class="constant-syntax">0x434F4D4D</span><span class="plain-syntax">) { </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"COMM"</span></span><span class="comment"> indicates common AIFF data</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">chunkLength</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">18</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> Check we have enough data to read</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int16</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, </span><span class="identifier-syntax">pChannels</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
@ -113,7 +113,7 @@ Durations are measured in centiseconds.
<span class="plain-syntax"> </span><span class="reserved-syntax">unsigned</span><span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> </span><span class="identifier-syntax">buffer</span><span class="plain-syntax">[256];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x4F676753</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"OggS"</span></code><span class="comment"> indicating an OGG file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x4F676753</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"OggS"</span></span><span class="comment"> indicating an OGG file</span>
<span class="plain-syntax"> </span><span class="comment"> Check OGG version is zero</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int8</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">version</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
@ -133,10 +133,10 @@ Durations are measured in centiseconds.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">packetType</span><span class="plain-syntax"> != </span><span class="constant-syntax">1</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">vorbisSig1</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">vorbisSig1</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x766F7262</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"VORB"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">vorbisSig1</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x766F7262</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"VORB"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int16</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">vorbisSig2</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">vorbisSig2</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x6973</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"IS"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">vorbisSig2</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x6973</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"IS"</span></span>
<span class="plain-syntax"> </span><span class="comment"> Check Vorbis version is zero</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">version</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
@ -160,7 +160,7 @@ Durations are measured in centiseconds.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">pBitsPerSecond</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="comment"> Search for the final Ogg page (near the end of the file) to read duration,</span>
<span class="plain-syntax"> </span><span class="comment"> i.e., read the last 4K of the file and look for the final </span><code class="display"><span class="extract-syntax">"OggS"</span></code><span class="comment"> sig</span>
<span class="plain-syntax"> </span><span class="comment"> i.e., read the last 4K of the file and look for the final </span><span class="extract"><span class="extract-syntax">"OggS"</span></span><span class="comment"> sig</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">fseek</span><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="identifier-syntax">SEEK_END</span><span class="plain-syntax">) != </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">fileLength</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">unsigned</span><span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax">) </span><span class="identifier-syntax">ftell</span><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">fileLength</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">4096</span><span class="plain-syntax">) </span><span class="identifier-syntax">seekPos</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
@ -191,7 +191,7 @@ Durations are measured in centiseconds.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">fseek</span><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, (</span><span class="reserved-syntax">long</span><span class="plain-syntax">) </span><span class="identifier-syntax">lastSig</span><span class="plain-syntax">, </span><span class="identifier-syntax">SEEK_SET</span><span class="plain-syntax">) != </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x4F676753</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"OggS"</span></code><span class="comment"> indicating an OGG file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x4F676753</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"OggS"</span></span><span class="comment"> indicating an OGG file</span>
<span class="plain-syntax"> </span><span class="comment"> Check OGG version is zero</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int8</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">version</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
@ -239,7 +239,7 @@ officially support MIDI, which makes the question moot.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"RIFF"</span></code><span class="comment"> indicating a RIFF file</span>
<span class="plain-syntax"> </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"RIFF"</span></span><span class="comment"> indicating a RIFF file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> == </span><span class="constant-syntax">0x52494646</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="comment"> Skip the filesize and typeID</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">fseek</span><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, </span><span class="constant-syntax">8</span><span class="plain-syntax">, </span><span class="identifier-syntax">SEEK_CUR</span><span class="plain-syntax">) != </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
@ -248,7 +248,7 @@ officially support MIDI, which makes the question moot.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"MThd"</span></code><span class="comment"> indicating a MIDI file</span>
<span class="plain-syntax"> </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"MThd"</span></span><span class="comment"> indicating a MIDI file</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> != </span><span class="constant-syntax">0x4D546864</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="comment"> Read length of chunk</span>
@ -293,7 +293,7 @@ officially support MIDI, which makes the question moot.
<span class="plain-syntax"> </span><span class="comment"> Skip any remaining bytes in the MThd chunk</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">fseek</span><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, (</span><span class="reserved-syntax">long</span><span class="plain-syntax">) (</span><span class="identifier-syntax">length</span><span class="plain-syntax"> - </span><span class="constant-syntax">6</span><span class="plain-syntax">), </span><span class="identifier-syntax">SEEK_CUR</span><span class="plain-syntax">) != </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="comment"> Keep reading chunks, looking for </span><code class="display"><span class="extract-syntax">"MTrk"</span></code>
<span class="plain-syntax"> </span><span class="comment"> Keep reading chunks, looking for </span><span class="extract"><span class="extract-syntax">"MTrk"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">do</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="comment"> Read chunk signature and length</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><a href="6-bf.html#SP1" class="function-link"><span class="function-syntax">BinaryFiles::read_int32</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">sig</span><span class="plain-syntax">)) {</span>
@ -304,7 +304,7 @@ officially support MIDI, which makes the question moot.
<span class="plain-syntax"> </span><span class="identifier-syntax">start_of_chunk_data</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">unsigned</span><span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax">) </span><span class="identifier-syntax">ftell</span><span class="plain-syntax">(</span><span class="identifier-syntax">pFile</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> == </span><span class="constant-syntax">0x4D54726B</span><span class="plain-syntax">) { </span><span class="comment"> </span><code class="display"><span class="extract-syntax">"MTrk"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sig</span><span class="plain-syntax"> == </span><span class="constant-syntax">0x4D54726B</span><span class="plain-syntax">) { </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">"MTrk"</span></span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"track starts\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="comment"> Read each event, looking for information before the real tune starts, e.g., tempo</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">do</span><span class="plain-syntax"> {</span>

48
docs/foundation-module/7-vn.html
View file

@ -48,7 +48,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="7-vn.html#SP1">&#167;1. Standard adoption</a></li><li><a href="7-vn.html#SP5">&#167;5. Printing and parsing</a></li><li><a href="7-vn.html#SP8">&#167;8. Precendence</a></li><li><a href="7-vn.html#SP11">&#167;11. Trichotomy</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Standard adoption. </b>The Semantic Version Number standard, semver 2.0.0, provides a strict set
of rules for the format and meaning of version numbers: see <code class="display"><span class="extract-syntax">https://semver.org</span></code>.
of rules for the format and meaning of version numbers: see <span class="extract"><span class="extract-syntax">https://semver.org</span></span>.
</p>
<p class="inwebparagraph">Prior to the standard most version numbers in computing usage looked like
@ -59,10 +59,10 @@ not be so strict on the textual form, which we will allow to be abbreviated.
Thus:
</p>
<ul class="items"><li>(a) The text <code class="display"><span class="extract-syntax">6.4.7</span></code> is understood to mean 6.4.7 and printed back as <code class="display"><span class="extract-syntax">6.4.7</span></code>
</li><li>(b) The text <code class="display"><span class="extract-syntax">6</span></code> is understood to mean 6.0.0 and printed back as <code class="display"><span class="extract-syntax">6</span></code>
</li><li>(c) The text <code class="display"><span class="extract-syntax">6.1</span></code> is understood to mean 6.1.0 and printed back as <code class="display"><span class="extract-syntax">6.1</span></code>
</li><li>(d) The text <code class="display"><span class="extract-syntax">6.1.0</span></code> is understood to mean 6.1.0 and printed back as <code class="display"><span class="extract-syntax">6.1.0</span></code>
<ul class="items"><li>(a) The text <span class="extract"><span class="extract-syntax">6.4.7</span></span> is understood to mean 6.4.7 and printed back as <span class="extract"><span class="extract-syntax">6.4.7</span></span>
</li><li>(b) The text <span class="extract"><span class="extract-syntax">6</span></span> is understood to mean 6.0.0 and printed back as <span class="extract"><span class="extract-syntax">6</span></span>
</li><li>(c) The text <span class="extract"><span class="extract-syntax">6.1</span></span> is understood to mean 6.1.0 and printed back as <span class="extract"><span class="extract-syntax">6.1</span></span>
</li><li>(d) The text <span class="extract"><span class="extract-syntax">6.1.0</span></span> is understood to mean 6.1.0 and printed back as <span class="extract"><span class="extract-syntax">6.1.0</span></span>
</li></ul>
<p class="inwebparagraph">Similarly, the absence of a version number (called "null" below) will be
understood to mean 0.0.0, but will be distinguished from the explicit choice
@ -70,8 +70,8 @@ to number something as 0.0.0.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>A complication is that Inform 7 extensions have for many years allowed two
forms of version number: either just <code class="display"><span class="extract-syntax">N</span></code>, which fits the scheme above, or
<code class="display"><span class="extract-syntax">N/DDDDDD</span></code>, which does not. This is a format which was chosen for sentimental
forms of version number: either just <span class="extract"><span class="extract-syntax">N</span></span>, which fits the scheme above, or
<span class="extract"><span class="extract-syntax">N/DDDDDD</span></span>, which does not. This is a format which was chosen for sentimental
reasons: IF enthusiasts know it well from the banner text of the Infocom
titles of the 1980s. This story file, for instance, was compiled at the
time of the Reykjavik summit between Presidents Gorbachev and Reagan:
@ -84,11 +84,11 @@ time of the Reykjavik summit between Presidents Gorbachev and Reagan:
<span class="plain-syntax"> Moonmist is a trademark of Infocom, Inc.</span>
<span class="plain-syntax"> Release number 9 / Serial number 861022</span>
</pre>
<p class="inwebparagraph">Story file collectors customarily abbreviate this in catalogues to <code class="display"><span class="extract-syntax">9/861022</span></code>.
<p class="inwebparagraph">Story file collectors customarily abbreviate this in catalogues to <span class="extract"><span class="extract-syntax">9/861022</span></span>.
</p>
<p class="inwebparagraph">We will therefore allow this notation, and convert it silently each way.
<code class="display"><span class="extract-syntax">N/DDDDDD</span></code> is equivalent to <code class="display"><span class="extract-syntax">N.DDDDDD</span></code>. Thus, <code class="display"><span class="extract-syntax">9/861022</span></code> means 9.861022.0 in
<span class="extract"><span class="extract-syntax">N/DDDDDD</span></span> is equivalent to <span class="extract"><span class="extract-syntax">N.DDDDDD</span></span>. Thus, <span class="extract"><span class="extract-syntax">9/861022</span></span> means 9.861022.0 in
semver precedence order.
</p>
@ -99,14 +99,14 @@ Such-and-Such by Me begins here", and so on: it would break all existing
extensions, for one thing, and it looks unfriendly.
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>In the array below, unspecified numbers are stored as <code class="display"><span class="extract-syntax">-1</span></code>. The three
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>In the array below, unspecified numbers are stored as <span class="extract"><span class="extract-syntax">-1</span></span>. The three
components are otherwise required to be non-negative integers.
</p>
<p class="inwebparagraph">Semver allows for more elaborate forms: for example <code class="display"><span class="extract-syntax">3.1.41-alpha.72.zeta+6Q45</span></code>
would mean 3.1.41 but with prerelease versioning <code class="display"><span class="extract-syntax">alpha.72.zeta</span></code> and build
metadata <code class="display"><span class="extract-syntax">6Q45</span></code>. The <code class="display"><span class="extract-syntax">prerelease_segments</span></code> list for this would be a list of
three texts: <code class="display"><span class="extract-syntax">alpha</span></code>, <code class="display"><span class="extract-syntax">72</span></code>, <code class="display"><span class="extract-syntax">zeta</span></code>.
<p class="inwebparagraph">Semver allows for more elaborate forms: for example <span class="extract"><span class="extract-syntax">3.1.41-alpha.72.zeta+6Q45</span></span>
would mean 3.1.41 but with prerelease versioning <span class="extract"><span class="extract-syntax">alpha.72.zeta</span></span> and build
metadata <span class="extract"><span class="extract-syntax">6Q45</span></span>. The <span class="extract"><span class="extract-syntax">prerelease_segments</span></span> list for this would be a list of
three texts: <span class="extract"><span class="extract-syntax">alpha</span></span>, <span class="extract"><span class="extract-syntax">72</span></span>, <span class="extract"><span class="extract-syntax">zeta</span></span>.
</p>
@ -116,7 +116,7 @@ three texts: <code class="display"><span class="extract-syntax">alpha</span></co
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">semantic_version_number</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">version_numbers</span><span class="plain-syntax">[</span><span class="constant-syntax">SEMVER_NUMBER_DEPTH</span><span class="plain-syntax">];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prerelease_segments</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">text_stream</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prerelease_segments</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">text_stream</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">build_metadata</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">semantic_version_number</span><span class="plain-syntax">;</span>
@ -127,7 +127,7 @@ three texts: <code class="display"><span class="extract-syntax">alpha</span></co
</pre><ul class="endnotetexts"><li>The structure semantic_version_number is accessed in 7/vnr and here.</li><li>The structure semantic_version_number_holder is private to this section.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>All invalid strings of numbers &mdash; i.e., breaking the above rules &mdash; are
called "null" versions, and can never be valid as the version of anything.
Instead they are used to represent the absence of a version number.
(In particular, a string of <code class="display"><span class="extract-syntax">-1</span></code>s is null.)
(In particular, a string of <span class="extract"><span class="extract-syntax">-1</span></span>s is null.)
</p>
<pre class="displayed-code all-displayed-code">
@ -171,9 +171,9 @@ Instead they are used to represent the absence of a version number.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">.</span><span class="identifier-syntax">build_metadata</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"+%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">.</span><span class="element-syntax">build_metadata</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>And this provides for the <code class="display"><span class="extract-syntax">%v</span></code> escape, though we must be careful when
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>And this provides for the <span class="extract"><span class="extract-syntax">%v</span></span> escape, though we must be careful when
using this to pass a pointer to the version, not the version itself;
variadic macros are not carefully enough type-checked by <code class="display"><span class="extract-syntax">clang</span></code> or <code class="display"><span class="extract-syntax">gcc</span></code>
variadic macros are not carefully enough type-checked by <span class="extract"><span class="extract-syntax">clang</span></span> or <span class="extract"><span class="extract-syntax">gcc</span></span>
to catch this sort of slip.
</p>
@ -183,9 +183,9 @@ to catch this sort of slip.
<span class="plain-syntax"> </span><a href="7-vn.html#SP5" class="function-link"><span class="function-syntax">VersionNumbers::to_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, *</span><span class="identifier-syntax">V</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>Parsing is much more of a slog. The following returns a null version if
the text <code class="display"><span class="extract-syntax">T</span></code> is in any respect malformed, i.e., if it deviates from the
the text <span class="extract"><span class="extract-syntax">T</span></span> is in any respect malformed, i.e., if it deviates from the
above specification in even the most trivial way. We parse the three parts
of a semver version in order: e.g. <code class="display"><span class="extract-syntax">3.1.41-alpha.72.zeta+6Q45</span></code> the first
of a semver version in order: e.g. <span class="extract"><span class="extract-syntax">3.1.41-alpha.72.zeta+6Q45</span></span> the first
part is up to the hyphen, the second part between the hyphen and the plus
sign, and the third part runs to the end. The second and third parts are
optional, but if both are given, they must be in that order.
@ -311,7 +311,7 @@ as if they were 0:
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>This returns a non-negative integer if <code class="display"><span class="extract-syntax">T</span></code> contains only digits, and <code class="display"><span class="extract-syntax">-1</span></code>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>This returns a non-negative integer if <span class="extract"><span class="extract-syntax">T</span></span> contains only digits, and <span class="extract"><span class="extract-syntax">-1</span></span>
otherwise. If the value has more than about 10 digits, then the result will
not be meaningful, which I think is a technical violation of the standard.
</p>
@ -326,8 +326,8 @@ not be meaningful, which I think is a technical violation of the standard.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="4-sm.html#SP7" class="function-link"><span class="function-syntax">Str::atoi</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. Trichotomy. </b>We now use the above function to construct ordering relations on semvers.
These are trichotomous, that is, for each pair <code class="display"><span class="extract-syntax">V1, V2</span></code>, exactly one of the
<code class="display"><span class="extract-syntax">VersionNumbers::eq(V1, V2)</span></code>, <code class="display"><span class="extract-syntax">VersionNumbers::gt(V1, V2)</span></code>, <code class="display"><span class="extract-syntax">VersionNumbers::lt(V1, V2)</span></code>
These are trichotomous, that is, for each pair <span class="extract"><span class="extract-syntax">V1, V2</span></span>, exactly one of the
<span class="extract"><span class="extract-syntax">VersionNumbers::eq(V1, V2)</span></span>, <span class="extract"><span class="extract-syntax">VersionNumbers::gt(V1, V2)</span></span>, <span class="extract"><span class="extract-syntax">VersionNumbers::lt(V1, V2)</span></span>
is true.
</p>
@ -353,7 +353,7 @@ is true.
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">VersionNumbers::lt</span><button class="popup" onclick="togglePopup('usagePopup13')">...<span class="popuptext" id="usagePopup13">Usage of <b>VersionNumbers::lt</b>:<br>Version Number Ranges - <a href="7-vnr.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">semantic_version_number</span><span class="plain-syntax"> </span><span class="identifier-syntax">V1</span><span class="plain-syntax">, </span><span class="reserved-syntax">semantic_version_number</span><span class="plain-syntax"> </span><span class="identifier-syntax">V2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> (</span><a href="7-vn.html#SP11" class="function-link"><span class="function-syntax">VersionNumbers::ge</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V1</span><span class="plain-syntax">, </span><span class="identifier-syntax">V2</span><span class="plain-syntax">))?</span><span class="identifier-syntax">FALSE:TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>And the following can be used for sorting, following the <code class="display"><span class="extract-syntax">strcmp</span></code> convention.
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>And the following can be used for sorting, following the <span class="extract"><span class="extract-syntax">strcmp</span></span> convention.
</p>
<pre class="displayed-code all-displayed-code">

30
docs/foundation-module/7-vnr.html
View file

@ -48,7 +48,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="7-vnr.html#SP1">&#167;1. Ranges</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Ranges. </b>We often want to check if a semver lies in a given precedence range, which we
store as an "interval" in the mathematical sense. For example, the range <code class="display"><span class="extract-syntax">[2,6)</span></code>
store as an "interval" in the mathematical sense. For example, the range <span class="extract"><span class="extract-syntax">[2,6)</span></span>
means all versions from 2.0.0 (inclusve) up to, but not equal to, 6.0.0. The
lower end is called "closed" because it includes the end-value 2.0.0, and the
upper end "open" because it does not. An infinite end means that there
@ -56,8 +56,8 @@ os no restriction in that direction; an empty end means that, in fact, the
interval is the empty set, that is, that no version number can ever satisfy it.
</p>
<p class="inwebparagraph">The <code class="display"><span class="extract-syntax">end_value</span></code> element is meaningful only for <code class="display"><span class="extract-syntax">CLOSED_RANGE_END</span></code> and <code class="display"><span class="extract-syntax">OPEN_RANGE_END</span></code>
ends. If one end is marked <code class="display"><span class="extract-syntax">EMPTY_RANGE_END</span></code>, so must the other be: it makes
<p class="inwebparagraph">The <span class="extract"><span class="extract-syntax">end_value</span></span> element is meaningful only for <span class="extract"><span class="extract-syntax">CLOSED_RANGE_END</span></span> and <span class="extract"><span class="extract-syntax">OPEN_RANGE_END</span></span>
ends. If one end is marked <span class="extract"><span class="extract-syntax">EMPTY_RANGE_END</span></span>, so must the other be: it makes
no sense for an interval to be empty seen from one end but not the other.
</p>
@ -79,8 +79,8 @@ no sense for an interval to be empty seen from one end but not the other.
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">range_end</span><span class="plain-syntax"> </span><span class="identifier-syntax">upper</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">semver_range</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure range_end is private to this section.</li><li>The structure semver_range is private to this section.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>As hinted above, the notation <code class="display"><span class="extract-syntax">[</span></code> and <code class="display"><span class="extract-syntax">]</span></code> is used for closed ends, and <code class="display"><span class="extract-syntax">(</span></code>
and <code class="display"><span class="extract-syntax">)</span></code> for open ones.
</pre><ul class="endnotetexts"><li>The structure range_end is private to this section.</li><li>The structure semver_range is private to this section.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>As hinted above, the notation <span class="extract"><span class="extract-syntax">[</span></span> and <span class="extract"><span class="extract-syntax">]</span></span> is used for closed ends, and <span class="extract"><span class="extract-syntax">(</span></span>
and <span class="extract"><span class="extract-syntax">)</span></span> for open ones.
</p>
<pre class="displayed-code all-displayed-code">
@ -119,15 +119,15 @@ number lies in this range.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The "compatibility" range for a given version lies at the heart of semver:
to be compatible with version <code class="display"><span class="extract-syntax">V</span></code>, version <code class="display"><span class="extract-syntax">W</span></code> must be of equal or greater
to be compatible with version <span class="extract"><span class="extract-syntax">V</span></span>, version <span class="extract"><span class="extract-syntax">W</span></span> must be of equal or greater
precedence, and must have the same major version number. For example,
for <code class="display"><span class="extract-syntax">2.1.7</span></code> the range will be <code class="display"><span class="extract-syntax">[2.1.7, 3-A)</span></code>, all versions at least 2.1.7 but
for <span class="extract"><span class="extract-syntax">2.1.7</span></span> the range will be <span class="extract"><span class="extract-syntax">[2.1.7, 3-A)</span></span>, all versions at least 2.1.7 but
not as high as 3.0.0-A.
</p>
<p class="inwebparagraph">Note that <code class="display"><span class="extract-syntax">3.0.0-A</span></code> is the least precendent version allowed by semver with
major version 3. The <code class="display"><span class="extract-syntax">-</span></code> gives it lower precedence than all release versions of
3.0.0; the fact that upper case <code class="display"><span class="extract-syntax">A</span></code> is alphabetically the earliest non-empty
<p class="inwebparagraph">Note that <span class="extract"><span class="extract-syntax">3.0.0-A</span></span> is the least precendent version allowed by semver with
major version 3. The <span class="extract"><span class="extract-syntax">-</span></span> gives it lower precedence than all release versions of
3.0.0; the fact that upper case <span class="extract"><span class="extract-syntax">A</span></span> is alphabetically the earliest non-empty
alphanumeric string gives it lower precendence than all other prerelease
versions.
</p>
@ -211,7 +211,7 @@ inclusive:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>The following decides which end restriction is stricter: it returns 1
of <code class="display"><span class="extract-syntax">E1</span></code> is, -1 if <code class="display"><span class="extract-syntax">E2</span></code> is, and 0 if they are equally onerous.
of <span class="extract"><span class="extract-syntax">E1</span></span> is, -1 if <span class="extract"><span class="extract-syntax">E2</span></span> is, and 0 if they are equally onerous.
</p>
<p class="inwebparagraph">The empty set is as strict as it gets: nothing qualifies.
@ -221,8 +221,8 @@ of <code class="display"><span class="extract-syntax">E1</span></code> is, -1 if
</p>
<p class="inwebparagraph">And otherwise, we need to know which end we're looking at in order to decide:
a lower end of <code class="display"><span class="extract-syntax">[4, ...]</span></code> is stricter than a lower end of <code class="display"><span class="extract-syntax">[3, ...]</span></code>, but an
upper end of <code class="display"><span class="extract-syntax">[..., 4]</span></code> is not as strict as an upper end of <code class="display"><span class="extract-syntax">[..., 3]</span></code>. Where
a lower end of <span class="extract"><span class="extract-syntax">[4, ...]</span></span> is stricter than a lower end of <span class="extract"><span class="extract-syntax">[3, ...]</span></span>, but an
upper end of <span class="extract"><span class="extract-syntax">[..., 4]</span></span> is not as strict as an upper end of <span class="extract"><span class="extract-syntax">[..., 3]</span></span>. Where
the boundary value is the same, open ends are stricter than closed ends.
</p>
@ -243,8 +243,8 @@ the boundary value is the same, open ends are stricter than closed ends.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>And so we finally arrive at the following, which intersects two ranges:
that is, it changes <code class="display"><span class="extract-syntax">R1</span></code> to the range of versions which lie inside both the
original <code class="display"><span class="extract-syntax">R1</span></code> and also <code class="display"><span class="extract-syntax">R2</span></code>. (This is used by Inbuild when an extension is
that is, it changes <span class="extract"><span class="extract-syntax">R1</span></span> to the range of versions which lie inside both the
original <span class="extract"><span class="extract-syntax">R1</span></span> and also <span class="extract"><span class="extract-syntax">R2</span></span>. (This is used by Inbuild when an extension is
included in two different places in the source text, but with possibly
different version needs.) The return value is true if an actual change took
place, and false otherwise.

2
docs/foundation-module/8-bdfw.html
View file

@ -116,10 +116,8 @@ convenient to store them directly here than to use a dictionary.
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Strict Usage Rules"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Off"</span><span class="plain-syntax">); </span><span class="identifier-syntax">bd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">on_or_off</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TeX Mathematics Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"$"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TeX Mathematics Displayed Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"$$"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TeX Mathematics Plugin"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"MathJax3"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Footnote Begins Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"["</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Footnote Ends Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"]"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Footnotes Plugin"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Bigfoot"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Code In Commentary Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"|"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Code In Code Comments Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"|"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">bd</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Cross-References Notation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"//"</span><span class="plain-syntax">);</span>

16
docs/foundation-module/8-bf.html
View file

@ -47,7 +47,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="8-bf.html#SP1">&#167;1. About build files</a></li><li><a href="8-bf.html#SP5">&#167;5. Bibliographic implications</a></li><li><a href="8-bf.html#SP7">&#167;7. Advancing</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. About build files. </b>When we read a web, we look for a file in it called <code class="display"><span class="extract-syntax">build.txt</span></code>. If no such
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. About build files. </b>When we read a web, we look for a file in it called <span class="extract"><span class="extract-syntax">build.txt</span></span>. If no such
file exists, we look for the same thing in the current working directory.
</p>
@ -136,7 +136,7 @@ called even if no build file had ever been found, so it's quite legal for
the Contents page to specify all of this.
</p>
<p class="inwebparagraph">If no error occurs, then the expansion <code class="display"><span class="extract-syntax">[[Semantic Version Number]]</span></code> is
<p class="inwebparagraph">If no error occurs, then the expansion <span class="extract"><span class="extract-syntax">[[Semantic Version Number]]</span></span> is
guaranteed to produce a semver-legal version number.
</p>
@ -184,8 +184,8 @@ number if we find that the date has changed.
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>The standard date format we use is "26 February 2018". If the contents of
<code class="display"><span class="extract-syntax">dateline</span></code> match today's date in this format, we return <code class="display"><span class="extract-syntax">TRUE</span></code>; otherwise we
rewrite <code class="display"><span class="extract-syntax">dateline</span></code> to today and return <code class="display"><span class="extract-syntax">FALSE</span></code>.
<span class="extract"><span class="extract-syntax">dateline</span></span> match today's date in this format, we return <span class="extract"><span class="extract-syntax">TRUE</span></span>; otherwise we
rewrite <span class="extract"><span class="extract-syntax">dateline</span></span> to today and return <span class="extract"><span class="extract-syntax">FALSE</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -204,11 +204,11 @@ rewrite <code class="display"><span class="extract-syntax">dateline</span></code
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">today</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Traditional Inform build codes are four-character, e.g., <code class="display"><span class="extract-syntax">3Q27</span></code>. Here, we
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Traditional Inform build codes are four-character, e.g., <span class="extract"><span class="extract-syntax">3Q27</span></span>. Here, we
read such a code and increase it by one. The two-digit code at the back is
incremented, but rolls around from <code class="display"><span class="extract-syntax">99</span></code> to <code class="display"><span class="extract-syntax">01</span></code>, in which case the letter is
advanced, except that <code class="display"><span class="extract-syntax">I</span></code> and <code class="display"><span class="extract-syntax">O</span></code> are skipped, and if the letter passes <code class="display"><span class="extract-syntax">Z</span></code>
then it rolls back around to <code class="display"><span class="extract-syntax">A</span></code> and the initial digit is incremented.
incremented, but rolls around from <span class="extract"><span class="extract-syntax">99</span></span> to <span class="extract"><span class="extract-syntax">01</span></span>, in which case the letter is
advanced, except that <span class="extract"><span class="extract-syntax">I</span></span> and <span class="extract"><span class="extract-syntax">O</span></span> are skipped, and if the letter passes <span class="extract"><span class="extract-syntax">Z</span></span>
then it rolls back around to <span class="extract"><span class="extract-syntax">A</span></span> and the initial digit is incremented.
</p>
<p class="inwebparagraph">This allows for 21384 distinct build codes, enough to use one each day for

36
docs/foundation-module/8-wm.html
View file

@ -50,7 +50,7 @@ function togglePopup(material_id) {
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Creation. </b>Each web of source material discovered by Inweb is given one of the following.
Ordinarily these are found only when reading in a web for weaving, tangling
and so on: in the vast majority of Inweb runs, all modules will have the
"module origin marker" <code class="display"><span class="extract-syntax">READING_WEB_MOM</span></code>. But when Inweb is constructing a
"module origin marker" <span class="extract"><span class="extract-syntax">READING_WEB_MOM</span></span>. But when Inweb is constructing a
makefile for a suite of tools, it can also discover multiple webs by other
means.
</p>
@ -66,11 +66,11 @@ means.
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">module</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">module_location</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">module_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dependencies</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">module</span></code><span class="comment">: which other modules does this need?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dependencies</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">module</span></span><span class="comment">: which other modules does this need?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">module_tag</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">origin_marker</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><code class="display"><span class="extract-syntax">*_MOM</span></code><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapters_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">chapter_md</span></code><span class="comment">: just the ones in this module</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">section_md</span></code><span class="comment">: just the ones in this module</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">origin_marker</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><span class="extract"><span class="extract-syntax">*_MOM</span></span><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapters_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">chapter_md</span></span><span class="comment">: just the ones in this module</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">section_md</span></span><span class="comment">: just the ones in this module</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">module</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure module is accessed in 8/ws and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b></p>
@ -92,9 +92,9 @@ contains a suite of utility routines, or a major component of a program, but
which is not a program in its own right.
</p>
<p class="inwebparagraph">Internally, though, every web produces a <code class="display"><span class="extract-syntax">module</span></code> structure. The one for the
<p class="inwebparagraph">Internally, though, every web produces a <span class="extract"><span class="extract-syntax">module</span></span> structure. The one for the
main web &mdash; which can be tangled, and results in an actual program &mdash; is
internally named <code class="display"><span class="extract-syntax">"(main)"</span></code>, a name which the user will never see.
internally named <span class="extract"><span class="extract-syntax">"(main)"</span></span>, a name which the user will never see.
</p>
<pre class="displayed-code all-displayed-code">
@ -129,8 +129,8 @@ program generated by A.
<span class="plain-syntax"> </span><span class="identifier-syntax">ms</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">path_to_search</span><span class="plain-syntax"> = </span><span class="identifier-syntax">ext_path</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">ms</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>When a web's contents page says to <code class="display"><span class="extract-syntax">import Blah</span></code>, how do we find the module
called <code class="display"><span class="extract-syntax">Blah</span></code> on disc? We try four possibilities in sequence:
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>When a web's contents page says to <span class="extract"><span class="extract-syntax">import Blah</span></span>, how do we find the module
called <span class="extract"><span class="extract-syntax">Blah</span></span> on disc? We try four possibilities in sequence:
</p>
<pre class="displayed-code all-displayed-code">
@ -151,7 +151,7 @@ called <code class="display"><span class="extract-syntax">Blah</span></code> on
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7_1"></a><b>&#167;7.1. </b>When the module is found (if it is), a suitable module structure is made,
and a dependency created from the web's <code class="display"><span class="extract-syntax">(main)</span></code> module to this one.
and a dependency created from the web's <span class="extract"><span class="extract-syntax">(main)</span></span> module to this one.
</p>
@ -171,23 +171,23 @@ sought if it looks like a web.
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">WebModules::exists</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>WebModules::exists</b>:<br><a href="8-wm.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="8-ws.html#SP8" class="function-link"><span class="function-syntax">WebMetadata::directory_looks_like_a_web</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Resolving cross-reference names. </b>Suppose we are in module <code class="display"><span class="extract-syntax">from_M</span></code> and want to understand which section of
a relevant web <code class="display"><span class="extract-syntax">text</span></code> might refer to. It could be the name of a module,
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Resolving cross-reference names. </b>Suppose we are in module <span class="extract"><span class="extract-syntax">from_M</span></span> and want to understand which section of
a relevant web <span class="extract"><span class="extract-syntax">text</span></span> might refer to. It could be the name of a module,
either this one or one dependent on it; or the name of a chapter in one
of those, or the shortened forms of those; or the name of a section. It
may match multiple possibilities: we return how many, and if this is
positive, we write the module in which the first find was made in <code class="display"><span class="extract-syntax">*return M</span></code>,
the section in <code class="display"><span class="extract-syntax">*return_Sm</span></code>, and set the flag <code class="display"><span class="extract-syntax">*named_as_module</span></code> according
positive, we write the module in which the first find was made in <span class="extract"><span class="extract-syntax">*return M</span></span>,
the section in <span class="extract"><span class="extract-syntax">*return_Sm</span></span>, and set the flag <span class="extract"><span class="extract-syntax">*named_as_module</span></span> according
to whether the reference was a bare module name (say, "foundation") or not.
</p>
<p class="inwebparagraph">Note that we consider first the possibilities within <code class="display"><span class="extract-syntax">from_M</span></code>: we only
<p class="inwebparagraph">Note that we consider first the possibilities within <span class="extract"><span class="extract-syntax">from_M</span></span>: we only
look at other modules if there are none. Thus, an unambiguous result in
<code class="display"><span class="extract-syntax">from_M</span></code> is good enough, even if there are other possibilities elsewhere.
<span class="extract"><span class="extract-syntax">from_M</span></span> is good enough, even if there are other possibilities elsewhere.
</p>
<p class="inwebparagraph">A reference in the form <code class="display"><span class="extract-syntax">module: reference</span></code> is taken to be in the module
of that name: for example, <code class="display"><span class="extract-syntax">"foundation: Web Modules"</span></code> would find the
<p class="inwebparagraph">A reference in the form <span class="extract"><span class="extract-syntax">module: reference</span></span> is taken to be in the module
of that name: for example, <span class="extract"><span class="extract-syntax">"foundation: Web Modules"</span></span> would find the
section of code you are now reading.
</p>

36
docs/foundation-module/8-ws.html
View file

@ -68,14 +68,14 @@ Our task in this section will be to read a web from the filing system and
produce the following metadata structure.
</p>
<p class="inwebparagraph">Each web produces a single instance of <code class="display"><span class="extract-syntax">web_md</span></code>:
<p class="inwebparagraph">Each web produces a single instance of <span class="extract"><span class="extract-syntax">web_md</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">web_md</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">path_to_web</span><span class="plain-syntax">; </span><span class="comment"> relative to the current working directory</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">single_file</span><span class="plain-syntax">; </span><span class="comment"> relative to the current working directory</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">bibliographic_data</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">web_bibliographic_datum</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">bibliographic_data</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">web_bibliographic_datum</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">semantic_version_number</span><span class="plain-syntax"> </span><span class="identifier-syntax">version_number</span><span class="plain-syntax">; </span><span class="comment"> as deduced from bibliographic data</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">default_syntax</span><span class="plain-syntax">; </span><span class="comment"> which version syntax the sections will have</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chaptered</span><span class="plain-syntax">; </span><span class="comment"> has the author explicitly divided it into named chapters?</span>
@ -83,20 +83,20 @@ produce the following metadata structure.
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">module</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_module</span><span class="plain-syntax">; </span><span class="comment"> the root of a small dependency graph</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">contents_filename</span><span class="plain-syntax">; </span><span class="comment"> or </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> for a single-file web</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tangle_target_names</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">text_stream</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">header_filenames</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">filename</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">contents_filename</span><span class="plain-syntax">; </span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> for a single-file web</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tangle_target_names</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">text_stream</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">header_filenames</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">filename</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapters_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">chapter_md</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">section_md</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapters_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">chapter_md</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">section_md</span></span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">web_md</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure web_md is accessed in 8/bdfw, 8/wm, 8/bf and here.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The <code class="display"><span class="extract-syntax">chapters_md</span></code> list in a <code class="display"><span class="extract-syntax">web_md</span></code> contains these as its entries:
</pre><ul class="endnotetexts"><li>The structure web_md is accessed in 8/bdfw, 8/wm, 8/bf and here.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The <span class="extract"><span class="extract-syntax">chapters_md</span></span> list in a <span class="extract"><span class="extract-syntax">web_md</span></span> contains these as its entries:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">chapter_md</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_range</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">P</span></code><span class="comment"> for Preliminaries, </span><code class="display"><span class="extract-syntax">7</span></code><span class="comment"> for Chapter 7, </span><code class="display"><span class="extract-syntax">C</span></code><span class="comment"> for Appendix C</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_range</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">P</span></span><span class="comment"> for Preliminaries, </span><span class="extract"><span class="extract-syntax">7</span></span><span class="comment"> for Chapter 7, </span><span class="extract"><span class="extract-syntax">C</span></span><span class="comment"> for Appendix C</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_title</span><span class="plain-syntax">; </span><span class="comment"> e.g., "Chapter 3: Fresh Water Fish"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_basic_title</span><span class="plain-syntax">; </span><span class="comment"> e.g., "Chapter 3"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_decorated_title</span><span class="plain-syntax">; </span><span class="comment"> e.g., "Fresh Water Fish"</span>
@ -106,10 +106,10 @@ produce the following metadata structure.
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">imported</span><span class="plain-syntax">; </span><span class="comment"> from a different web?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">section_md</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections_md</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">section_md</span></span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">chapter_md</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure chapter_md is accessed in 8/wm and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>And the <code class="display"><span class="extract-syntax">sections_md</span></code> list in a <code class="display"><span class="extract-syntax">chapter_md</span></code> contains these as its entries:
</pre><ul class="endnotetexts"><li>The structure chapter_md is accessed in 8/wm and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>And the <span class="extract"><span class="extract-syntax">sections_md</span></span> list in a <span class="extract"><span class="extract-syntax">chapter_md</span></span> contains these as its entries:
</p>
<pre class="displayed-code all-displayed-code">
@ -130,9 +130,9 @@ produce the following metadata structure.
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">section_md</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure section_md is accessed in 5/htm, 8/wm and here.</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Reading from the file system. </b>Webs can be stored in two ways: as a directory containing a multitude of files,
in which case the pathname <code class="display"><span class="extract-syntax">P</span></code> is supplied; or as a single file with everything
in which case the pathname <span class="extract"><span class="extract-syntax">P</span></span> is supplied; or as a single file with everything
in one (and thus, implicitly, a single chapter and a single section), in which
case a filename <code class="display"><span class="extract-syntax">alt_F</span></code> is supplied.
case a filename <span class="extract"><span class="extract-syntax">alt_F</span></span> is supplied.
</p>
<pre class="displayed-code all-displayed-code">
@ -299,7 +299,7 @@ would be "elctrcty", since we don't count "y" as a vowel here.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">original_range</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="8-ws.html#SP5_4_1">&#167;5.4.1</a>.</li></ul><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. Reading the contents page. </b>Making the web begins by reading the contents section, which really isn't a
section at all (and perhaps we shouldn't pretend that it is by the use of the
<code class="display"><span class="extract-syntax">.w</span></code> file extension, but we probably want it to have the same file extension,
<span class="extract"><span class="extract-syntax">.w</span></span> file extension, but we probably want it to have the same file extension,
and its syntax is chosen so that syntax-colouring for regular sections doesn't
make it look odd). When the word "section" is used in the Inweb code, it
almost always means "section other than the contents".
@ -431,7 +431,7 @@ immediately.
<span class="plain-syntax"> </span><span class="identifier-syntax">RS</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">Wm</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_syntax</span><span class="plain-syntax"> = </span><span class="constant-syntax">V1_SYNTAX</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Web Syntax Version: 2"</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RS</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">Wm</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_syntax</span><span class="plain-syntax"> = </span><span class="constant-syntax">V2_SYNTAX</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="8-ws.html#SP7">&#167;7</a>.</li></ul><p class="inwebparagraph"><a id="SP7_2"></a><b>&#167;7.2. </b>Suppose we're reading a single-file web, and we hit the first <code class="display"><span class="extract-syntax">@</span></code> marker.
</pre><ul class="endnotetexts"><li>This code is used in <a href="8-ws.html#SP7">&#167;7</a>.</li></ul><p class="inwebparagraph"><a id="SP7_2"></a><b>&#167;7.2. </b>Suppose we're reading a single-file web, and we hit the first <span class="extract"><span class="extract-syntax">@</span></span> marker.
The contents part has now ended, so we should halt scanning. But we also need
to give the web a single chapter ("Sections", range "S"), which contains a
single section ("All") consisting of the remainder of the single file.
@ -783,9 +783,9 @@ we also read in and process its file.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">p</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">p</span><span class="plain-syntax"> = </span><a href="8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::get_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">RS</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">Wm</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Language"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Sm</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_independent_language</span><span class="plain-syntax"> = </span><a href="4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">p</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="8-ws.html#SP7_2_2_3">&#167;7.2.2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP7_2_2_4"></a><b>&#167;7.2.2.4. </b>If we're told that a section is called "Bells and Whistles", what filename
is it stored in? Firstly, the leafname is normally <code class="display"><span class="extract-syntax">Bells and Whistles.w</span></code>,
but the extension used doesn't have to be <code class="display"><span class="extract-syntax">.w</span></code>: for Inform 6 template files,
the extension needs to be <code class="display"><span class="extract-syntax">.i6t</span></code>. We allow either.
is it stored in? Firstly, the leafname is normally <span class="extract"><span class="extract-syntax">Bells and Whistles.w</span></span>,
but the extension used doesn't have to be <span class="extract"><span class="extract-syntax">.w</span></span>: for Inform 6 template files,
the extension needs to be <span class="extract"><span class="extract-syntax">.i6t</span></span>. We allow either.
</p>

82
docs/foundation-module/P-abgtf.html
View file

@ -88,7 +88,7 @@ can be found in <a href="../foundation-test/index.html" class="internal">foundat
and chapters.
</p>
<p class="inwebparagraph">2. The constant <code class="display"><span class="extract-syntax">PROGRAM_NAME</span></code> must be defined equal to a C string with a
<p class="inwebparagraph">2. The constant <span class="extract"><span class="extract-syntax">PROGRAM_NAME</span></span> must be defined equal to a C string with a
brief version of the program's name. For example,
</p>
@ -97,14 +97,14 @@ brief version of the program's name. For example,
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph">3. The <code class="display"><span class="extract-syntax">main</span></code> function for the client should, as one of its very first acts,
call <code class="display"><span class="extract-syntax">Foundation::start()</span></code>, and should similarly, just before it exits, call
<code class="display"><span class="extract-syntax">Foundation::end()</span></code>. Any other module used should be started after Foundation
<p class="inwebparagraph">3. The <span class="extract"><span class="extract-syntax">main</span></span> function for the client should, as one of its very first acts,
call <span class="extract"><span class="extract-syntax">Foundation::start()</span></span>, and should similarly, just before it exits, call
<span class="extract"><span class="extract-syntax">Foundation::end()</span></span>. Any other module used should be started after Foundation
starts, and ended before Foundation ends.
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Truth. </b>Every large C program starts by defining constants for truth and falsity. So
does Foundation: <code class="display"><span class="extract-syntax">TRUE</span></code>, <code class="display"><span class="extract-syntax">FALSE</span></code>, and a third state <code class="display"><span class="extract-syntax">NOT_APPLICABLE</span></code>.
does Foundation: <span class="extract"><span class="extract-syntax">TRUE</span></span>, <span class="extract"><span class="extract-syntax">FALSE</span></span>, and a third state <span class="extract"><span class="extract-syntax">NOT_APPLICABLE</span></span>.
</p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Text streams and formatted output. </b>Perhaps the most useful feature of Foundation is that it provides for
@ -122,9 +122,9 @@ length of a text in memory runs in \(O(1)\) time.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"According to %S, the square of %d is %d.\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">authority</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">*</span><span class="identifier-syntax">N</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<p class="inwebparagraph">Here <code class="display"><span class="extract-syntax">WRITE</span></code> is a variadic macro rather like <code class="display"><span class="extract-syntax">printf</span></code>, and note the use of
the escape <code class="display"><span class="extract-syntax">%S</span></code> to write a text stream. It writes formatted output into the
stream <code class="display"><span class="extract-syntax">OUT</span></code>, and is actually an abbreviation for this:
<p class="inwebparagraph">Here <span class="extract"><span class="extract-syntax">WRITE</span></span> is a variadic macro rather like <span class="extract"><span class="extract-syntax">printf</span></span>, and note the use of
the escape <span class="extract"><span class="extract-syntax">%S</span></span> to write a text stream. It writes formatted output into the
stream <span class="extract"><span class="extract-syntax">OUT</span></span>, and is actually an abbreviation for this:
</p>
<pre class="displayed-code all-displayed-code">
@ -132,20 +132,20 @@ stream <code class="display"><span class="extract-syntax">OUT</span></code>, and
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="string-syntax">"According to %S, the square of %d is %d.\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">authority</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">*</span><span class="identifier-syntax">N</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<p class="inwebparagraph">The function <code class="display"><span class="extract-syntax">Hypothetical::writer</span></code> can write equally to a text file or to a
<p class="inwebparagraph">The function <span class="extract"><span class="extract-syntax">Hypothetical::writer</span></span> can write equally to a text file or to a
string, whichever it's given, and doesn't need to worry about memory management
or text encodings.
</p>
<p class="inwebparagraph">The standard output and standard error "files" on Unix-based systems are
referred to as <code class="display"><span class="extract-syntax">STDOUT</span></code> and <code class="display"><span class="extract-syntax">STDERR</span></code>, both constants of type <code class="display"><span class="extract-syntax">text_stream *</span></code>
defined by Foundation. The value <code class="display"><span class="extract-syntax">NULL</span></code>, used as a text stream, is valid and
referred to as <span class="extract"><span class="extract-syntax">STDOUT</span></span> and <span class="extract"><span class="extract-syntax">STDERR</span></span>, both constants of type <span class="extract"><span class="extract-syntax">text_stream *</span></span>
defined by Foundation. The value <span class="extract"><span class="extract-syntax">NULL</span></span>, used as a text stream, is valid and
prints as the empty string, while ignoring any content written to it.
All of these capitalised macros are defined in <a href="2-str.html" class="internal">Streams</a>.
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">PRINT("...")</span></code> is an abbreviation for <code class="display"><span class="extract-syntax">WRITE_TO(STDOUT, "...")</span></code>, and
<code class="display"><span class="extract-syntax">LOG("...")</span></code> similarly writes to the log file. (See <a href="2-dl.html" class="internal">Debugging Log</a>.)
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">PRINT("...")</span></span> is an abbreviation for <span class="extract"><span class="extract-syntax">WRITE_TO(STDOUT, "...")</span></span>, and
<span class="extract"><span class="extract-syntax">LOG("...")</span></span> similarly writes to the log file. (See <a href="2-dl.html" class="internal">Debugging Log</a>.)
</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>If you're using <a href="../inweb/M-tid.html" class="internal">The InC Dialect (in inweb)</a>, the slight extension to C made
@ -155,7 +155,7 @@ by Inweb, there's a simple notation for constants of this type:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">error_message</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"quadro-triticale stocks depleted"</span><span class="plain-syntax">;</span>
</pre>
<p class="inwebparagraph">The <code class="display"><span class="extract-syntax">I</span></code> prefix is meant to imitate the <code class="display"><span class="extract-syntax">L</span></code> used in standard C99 for long string
<p class="inwebparagraph">The <span class="extract"><span class="extract-syntax">I</span></span> prefix is meant to imitate the <span class="extract"><span class="extract-syntax">L</span></span> used in standard C99 for long string
constants. But this is a feature of <a href="../inweb/index.html" class="internal">inweb</a> rather than of Foundation.
</p>
@ -174,15 +174,15 @@ momentary period, do this:
<span class="plain-syntax"> ...</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">alpha</span><span class="plain-syntax">);</span>
</pre>
<p class="inwebparagraph">Between the use of these two macros, <code class="display"><span class="extract-syntax">alpha</span></code> is a valid <code class="display"><span class="extract-syntax">text_stream *</span></code>,
<p class="inwebparagraph">Between the use of these two macros, <span class="extract"><span class="extract-syntax">alpha</span></span> is a valid <span class="extract"><span class="extract-syntax">text_stream *</span></span>,
and is a string capable of growing to arbitrary size.
</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>Foundation provides an elaborate system for providing new string escapes
like <code class="display"><span class="extract-syntax">%S</span></code>: see <a href="2-wal.html" class="internal">Writers and Loggers</a>. A similar system manages a debugging
like <span class="extract"><span class="extract-syntax">%S</span></span>: see <a href="2-wal.html" class="internal">Writers and Loggers</a>. A similar system manages a debugging
log, to which it's easy to make "dollar escapes" for pretty-printing internal
data structures: for example, if you've made a structure called <code class="display"><span class="extract-syntax">recipe</span></code>, you
could make <code class="display"><span class="extract-syntax">$R</span></code> pretty-print one.
data structures: for example, if you've made a structure called <span class="extract"><span class="extract-syntax">recipe</span></span>, you
could make <span class="extract"><span class="extract-syntax">$R</span></span> pretty-print one.
</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>Foundation also has an extensive library of string-handling routines,
@ -200,7 +200,7 @@ benefit of functions like <a href="4-sm.html#SP26" class="internal">Str::substr<
</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Individual characters are represented in Foundation using the standard
POSIX type <code class="display"><span class="extract-syntax">wchar_t</span></code>, which on all modern systems is a very wide integer,
POSIX type <span class="extract"><span class="extract-syntax">wchar_t</span></span>, which on all modern systems is a very wide integer,
whether or not signed. It's safe to assume it can hold all normal Unicode
code points. See <a href="4-chr.html" class="internal">Characters</a> for class functions like <a href="4-chr.html#SP1" class="internal">Characters::isdigit</a>,
which have been carefully written to work equivalently on either Windows or
@ -208,7 +208,7 @@ Unix-based systems.
</p>
<p class="inwebparagraph"><a href="4-cst.html" class="internal">C Strings</a> and <a href="4-ws.html" class="internal">Wide Strings</a> provide bare-minimum facilities for handling
traditional null-terminated <code class="display"><span class="extract-syntax">char</span></code> and <code class="display"><span class="extract-syntax">wchar_t</span></code> arrays, but don't use these.
traditional null-terminated <span class="extract"><span class="extract-syntax">char</span></span> and <span class="extract"><span class="extract-syntax">wchar_t</span></span> arrays, but don't use these.
Texts are just better.
</p>
@ -219,7 +219,7 @@ in C which corresponds to objects of the class "recipe". We need to do three
things:
</p>
<ul class="items"><li>(1) Declare an enumerated constant ending <code class="display"><span class="extract-syntax">_MT</span></code> to represent this type in the
<ul class="items"><li>(1) Declare an enumerated constant ending <span class="extract"><span class="extract-syntax">_MT</span></span> to represent this type in the
memory manager, and then make a matching use of a macro to define some associated
functions, which we never see or think about. For example:
</p>
@ -249,7 +249,7 @@ of throwaway instances, we would instead write:
actually needed.
</p>
</li><li>(2) We have to declare the actual structure, and <code class="display"><span class="extract-syntax">typedef</span></code> the name to it. For
</li><li>(2) We have to declare the actual structure, and <span class="extract"><span class="extract-syntax">typedef</span></span> the name to it. For
example:
</p>
@ -260,18 +260,18 @@ example:
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax"> } </span><span class="identifier-syntax">recipe</span><span class="plain-syntax">;</span>
</pre>
<p class="inwebparagraph">Here <code class="display"><span class="extract-syntax">MEMORY_MANAGEMENT</span></code> is a macro defined in <a href="2-mmr.html" class="internal">Memory</a> which expands to the
<p class="inwebparagraph">Here <span class="extract"><span class="extract-syntax">MEMORY_MANAGEMENT</span></span> is a macro defined in <a href="2-mmr.html" class="internal">Memory</a> which expands to the
necessary field(s) to keep track of this. We won't use those fields, or ever
think about them.
</p>
</li><li>(3) In fact we've now finished. The macro <code class="display"><span class="extract-syntax">CREATE(recipe)</span></code> returns a new
instance, and <code class="display"><span class="extract-syntax">DESTROY(R)</span></code> would destroy an existing one, <code class="display"><span class="extract-syntax">R</span></code>. Unless manually
</li><li>(3) In fact we've now finished. The macro <span class="extract"><span class="extract-syntax">CREATE(recipe)</span></span> returns a new
instance, and <span class="extract"><span class="extract-syntax">DESTROY(R)</span></span> would destroy an existing one, <span class="extract"><span class="extract-syntax">R</span></span>. Unless manually
destroyed, objects last forever; there is no garbage collection. In practice
the Inform tools suite, for which Foundation was written, almost never destroy
objects.
</li></ul>
<p class="inwebparagraph">Customarily, though, we wrap the use of <code class="display"><span class="extract-syntax">CREATE</span></code> in a constructor function:
<p class="inwebparagraph">Customarily, though, we wrap the use of <span class="extract"><span class="extract-syntax">CREATE</span></span> in a constructor function:
</p>
<pre class="displayed-code all-displayed-code">
@ -284,7 +284,7 @@ objects.
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph">We also often use the convenient <code class="display"><span class="extract-syntax">LOOP_OVER</span></code> macro:
<p class="inwebparagraph">We also often use the convenient <span class="extract"><span class="extract-syntax">LOOP_OVER</span></span> macro:
</p>
<pre class="displayed-code all-displayed-code">
@ -295,7 +295,7 @@ objects.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"- %S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">name_of_dish</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">LOOP_OVER</span></code> loops through all created recipe instances (which have not been
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">LOOP_OVER</span></span> loops through all created recipe instances (which have not been
destroyed).
</p>
@ -305,7 +305,7 @@ allocate memory for arrays &mdash; see <a href="2-mmr.html#SP25" class="internal
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. Methods. </b>It's also possible to have method calls on object instances, though the
syntax is not as tidy as it would be in an object-oriented language. To allow
this for <code class="display"><span class="extract-syntax">recipe</span></code>, we would have to add another line to the structure:
this for <span class="extract"><span class="extract-syntax">recipe</span></span>, we would have to add another line to the structure:
</p>
<pre class="displayed-code all-displayed-code">
@ -322,8 +322,8 @@ this for <code class="display"><span class="extract-syntax">recipe</span></code>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">R</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">methods</span><span class="plain-syntax"> = </span><span class="function-syntax">Methods::new_set</span><span class="plain-syntax">();</span>
</pre>
<p class="inwebparagraph">The object <code class="display"><span class="extract-syntax">R</span></code> is then ready to receive method calls. Each different call needs
an enumerated constant ending <code class="display"><span class="extract-syntax">_MTID</span></code> to identify it, and an indication of the
<p class="inwebparagraph">The object <span class="extract"><span class="extract-syntax">R</span></span> is then ready to receive method calls. Each different call needs
an enumerated constant ending <span class="extract"><span class="extract-syntax">_MTID</span></span> to identify it, and an indication of the
type of the function call involved:
</p>
@ -335,7 +335,7 @@ type of the function call involved:
<span class="plain-syntax"> =</span>
<span class="plain-syntax"> VMETHOD_TYPE(COOK_MTID, recipe *R, int time_in_oven)</span>
</pre>
<p class="inwebparagraph">The <code class="display"><span class="extract-syntax">V</span></code> here means that this will be a void function, that is, returning no
<p class="inwebparagraph">The <span class="extract"><span class="extract-syntax">V</span></span> here means that this will be a void function, that is, returning no
value. It's now possible to call this on any recipe:
</p>
@ -343,7 +343,7 @@ value. It's now possible to call this on any recipe:
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">duck_a_l_orange</span><span class="plain-syntax">, </span><span class="identifier-syntax">COOK_MTID</span><span class="plain-syntax">, </span><span class="constant-syntax">45</span><span class="plain-syntax">);</span>
</pre>
<p class="inwebparagraph">What then happens? Nothing at all, unless the recipe instance in question &mdash;
here, <code class="display"><span class="extract-syntax">duck_a_l_orange</span></code> &mdash; has been given a receiver function. Let's revisit
here, <span class="extract"><span class="extract-syntax">duck_a_l_orange</span></span> &mdash; has been given a receiver function. Let's revisit
the constructor function for recipes:
</p>
@ -379,17 +379,17 @@ the effect of
<span class="plain-syntax"> </span><span class="identifier-syntax">Recipes::cook</span><span class="plain-syntax">(</span><span class="identifier-syntax">duck_a_l_orange</span><span class="plain-syntax">, </span><span class="constant-syntax">45</span><span class="plain-syntax">);</span>
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>In fact it's possible to attach multiple receivers to the same object, in
which case they each run in turn. As a variant on this, methods can also return
their "success". If multiple receivers run, the first to return <code class="display"><span class="extract-syntax">TRUE</span></code> has
their "success". If multiple receivers run, the first to return <span class="extract"><span class="extract-syntax">TRUE</span></span> has
claimed the right to act, and subsequent receivers aren't consulted.
</p>
<p class="inwebparagraph">Such methods must be defined with <code class="display"><span class="extract-syntax">IMETHOD_CALL</span></code> and are rarely needed. See
<p class="inwebparagraph">Such methods must be defined with <span class="extract"><span class="extract-syntax">IMETHOD_CALL</span></span> and are rarely needed. See
<a href="2-mth.html" class="internal">Methods</a> for more.
</p>
<p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. Collections. </b>Foundation provides three sorts of "collection": see <a href="2-llas.html" class="internal">Linked Lists and Stacks</a>,
and also <a href="2-dct.html" class="internal">Dictionaries</a>. These all collect values which are expected to be
pointers: for example, text streams (of type <code class="display"><span class="extract-syntax">text_stream *</span></code>) or objects like
pointers: for example, text streams (of type <span class="extract"><span class="extract-syntax">text_stream *</span></span>) or objects like
the ones created above. For example,
</p>
@ -443,7 +443,7 @@ directories might be.
</p>
<p class="inwebparagraph">Both tend to refer relative to the current working directory, represented by
the null <code class="display"><span class="extract-syntax">pathname</span></code> pointer. <a href="3-pth.html#SP7" class="internal">Pathnames::up</a> and <a href="3-pth.html#SP4" class="internal">Pathnames::down</a> go
the null <span class="extract"><span class="extract-syntax">pathname</span></span> pointer. <a href="3-pth.html#SP7" class="internal">Pathnames::up</a> and <a href="3-pth.html#SP4" class="internal">Pathnames::down</a> go
to parent or subdirectories, respectively. A filename cannot exist without
a pathname; for example,
</p>
@ -454,13 +454,13 @@ a pathname; for example,
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="function-syntax">Filenames::in</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"options.txt"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PRINT</span><span class="plain-syntax">(</span><span class="string-syntax">"I have arrived at %f.\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
</pre>
<p class="inwebparagraph">produces, on platforms where <code class="display"><span class="extract-syntax">/</span></code> is used as the file system dividing character,
<p class="inwebparagraph">produces, on platforms where <span class="extract"><span class="extract-syntax">/</span></span> is used as the file system dividing character,
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> I have arrived at App/Config/options.txt.</span>
</pre>
<p class="inwebparagraph">Note the use of the escape <code class="display"><span class="extract-syntax">%f</span></code> for printing filenames; there's also <code class="display"><span class="extract-syntax">%p</span></code> for
<p class="inwebparagraph">Note the use of the escape <span class="extract"><span class="extract-syntax">%f</span></span> for printing filenames; there's also <span class="extract"><span class="extract-syntax">%p</span></span> for
pathnames.
</p>
@ -483,7 +483,7 @@ for endian-ness.
<p class="inwebparagraph"><a id="SP18"></a><b>&#167;18. </b><a href="4-tf.html" class="internal">Text Files</a> allows us to read text files. Its most useful function is
<a href="4-tf.html#SP5" class="internal">TextFiles::read</a>, which opens a file, can print an error if it doesn't
exist, and if it does, then feeds the lines one at a time to an iterator.
For example, if <code class="display"><span class="extract-syntax">F</span></code> is a filename, the following reads the file into a
For example, if <span class="extract"><span class="extract-syntax">F</span></span> is a filename, the following reads the file into a
linked list of texts:
</p>
@ -519,7 +519,7 @@ sections (of <a href="8-ws.html#SP4" class="internal">section_md</a>).
</p>
<ul class="items"><li>(a) <a href="3-tm.html" class="internal">Time</a> for the time of day and the date of Easter (no, really);
</li><li>(b) <a href="3-shl.html" class="internal">Shell</a> for issuing shell commands via the C library's <code class="display"><span class="extract-syntax">system</span></code> function,
</li><li>(b) <a href="3-shl.html" class="internal">Shell</a> for issuing shell commands via the C library's <span class="extract"><span class="extract-syntax">system</span></span> function,
or its equivalent;
</li><li>(c) <a href="5-htm.html" class="internal">HTML</a> and <a href="5-ee.html" class="internal">Epub Ebooks</a> for generating web pages and ebooks;
</li><li>(d) <a href="6-id.html" class="internal">Image Dimensions</a> and <a href="6-sd.html" class="internal">Sound Durations</a> for handling videos and music;

2
docs/goldbach/S-sp.html
View file

@ -67,7 +67,7 @@ number greater than 2 can be written this way. This remains open, though &mdash;
<ul class="items"><li>(a) every even number is a sum of at most six primes (Ramaré, 1995), and
</li><li>(b) every odd number is a sum of at most five (Tao, 2012).
</li></ul>
<p class="inwebparagraph">Besides which, <code class="display"><span class="extract-syntax">printf(k+1)</span></code>, to say the least: see <a href="http://www.google.com" class="external">http://www.google.com</a>
<p class="inwebparagraph">Besides which, <span class="extract"><span class="extract-syntax">printf(k+1)</span></span>, to say the least: see <a href="http://www.google.com" class="external">http://www.google.com</a>
or for that matter see <a href="S-tsoe.html" class="internal">The Sieve of Eratosthenes</a>.
</p>

4
docs/goldbach/S-tsoe.html
View file

@ -78,8 +78,8 @@ for primality.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (!</span><span class="identifier-syntax">sieve_performed</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">Perform the sieve</span> <span class="named-paragraph-number">2.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">still_in_sieve</span><span class="plain-syntax">[</span><span class="identifier-syntax">n</span><span class="plain-syntax">];</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b>We save a little time by noting that if a number up to <code class="display"><span class="extract-syntax">RANGE</span></code> is composite
then one of its factors must be smaller than the square root of <code class="display"><span class="extract-syntax">RANGE</span></code>. Thus,
</pre><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b>We save a little time by noting that if a number up to <span class="extract"><span class="extract-syntax">RANGE</span></span> is composite
then one of its factors must be smaller than the square root of <span class="extract"><span class="extract-syntax">RANGE</span></span>. Thus,
in a sieve of size 10000, one only needs to remove multiples of 2 up to 100,
for example.
</p>

66
docs/inweb/1-cnf.html
View file

@ -53,43 +53,43 @@ command line: there will only ever be one of these.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">inweb_instructions</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">inweb_mode</span><span class="plain-syntax">; </span><span class="comment"> our main mode of operation: one of the </span><code class="display"><span class="extract-syntax">*_MODE</span></code><span class="comment"> constants</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">inweb_mode</span><span class="plain-syntax">; </span><span class="comment"> our main mode of operation: one of the </span><span class="extract"><span class="extract-syntax">*_MODE</span></span><span class="comment"> constants</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chosen_web</span><span class="plain-syntax">; </span><span class="comment"> project folder relative to cwd</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chosen_file</span><span class="plain-syntax">; </span><span class="comment"> or, single file relative to cwd</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chosen_range</span><span class="plain-syntax">; </span><span class="comment"> which subset of this web we apply to (often, all of it)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">chosen_range_actually_chosen</span><span class="plain-syntax">; </span><span class="comment"> rather than being a default choice</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">swarm_mode</span><span class="plain-syntax">; </span><span class="comment"> relevant to weaving only: one of the </span><code class="display"><span class="extract-syntax">*_SWARM</span></code><span class="comment"> constants</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tag_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-weave-tag X</span></code><span class="comment">: weave, but only the material tagged X</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-weave-as X</span></code><span class="comment">: for example, </span><code class="display"><span class="extract-syntax">-weave-to HTML</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">swarm_mode</span><span class="plain-syntax">; </span><span class="comment"> relevant to weaving only: one of the </span><span class="extract"><span class="extract-syntax">*_SWARM</span></span><span class="comment"> constants</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tag_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-weave-tag X</span></span><span class="comment">: weave, but only the material tagged X</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-weave-as X</span></span><span class="comment">: for example, </span><span class="extract"><span class="extract-syntax">-weave-to HTML</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">show_languages_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-show-languages</span></code><span class="comment">: print list of available PLs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">catalogue_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-catalogue</span></code><span class="comment">: print catalogue of sections</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">functions_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-functions</span></code><span class="comment">: print catalogue of functions within sections</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">structures_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-structures</span></code><span class="comment">: print catalogue of structures within sections</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">advance_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-advance-build</span></code><span class="comment">: advance build file for web</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">open_pdf_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-open-pdf</span></code><span class="comment">: open any woven PDF in the OS once it is made</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">scan_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-scan</span></code><span class="comment">: simply show the syntactic scan of the source</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_to_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-weave-to X</span></code><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_into_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-weave-into X</span></code><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">show_languages_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-show-languages</span></span><span class="comment">: print list of available PLs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">catalogue_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-catalogue</span></span><span class="comment">: print catalogue of sections</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">functions_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-functions</span></span><span class="comment">: print catalogue of functions within sections</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">structures_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-structures</span></span><span class="comment">: print catalogue of structures within sections</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">advance_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-advance-build</span></span><span class="comment">: advance build file for web</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">open_pdf_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-open-pdf</span></span><span class="comment">: open any woven PDF in the OS once it is made</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">scan_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-scan</span></span><span class="comment">: simply show the syntactic scan of the source</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_to_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-weave-to X</span></span><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_into_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-weave-into X</span></span><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sequential</span><span class="plain-syntax">; </span><span class="comment"> give the sections sequential sigils</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tangle_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-tangle-to X</span></code><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">makefile_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-makefile X</span></code><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gitignore_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-gitignore X</span></code><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">advance_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-advance-build-file X</span></code><span class="comment">: advance build file X</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">writeme_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-write-me X</span></code><span class="comment">: advance build file X</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prototype_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-prototype X</span></code><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">navigation_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-navigation X</span></code><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colony_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-colony X</span></code><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">member_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-member X</span></code><span class="comment">: sets web to member X of colony</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">breadcrumb_setting</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">breadcrumb_request</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">verbose_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-verbose</span></code><span class="comment">: print names of files read to stdout</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tangle_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-tangle-to X</span></span><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">makefile_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-makefile X</span></span><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gitignore_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-gitignore X</span></span><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">advance_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-advance-build-file X</span></span><span class="comment">: advance build file X</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">writeme_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-write-me X</span></span><span class="comment">: advance build file X</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prototype_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-prototype X</span></span><span class="comment">: the pathname X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">navigation_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-navigation X</span></span><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colony_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-colony X</span></span><span class="comment">: the filename X, if supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">member_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-member X</span></span><span class="comment">: sets web to member X of colony</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">breadcrumb_setting</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">breadcrumb_request</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">verbose_switch</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-verbose</span></span><span class="comment">: print names of files read to stdout</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">targets</span><span class="plain-syntax">; </span><span class="comment"> used only for parsing</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">test_language_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-test-language X</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">test_language_on_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-test-language-on X</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">test_language_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-test-language X</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">test_language_on_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-test-language-on X</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">import_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">-import X</span></code><span class="comment">: where to find imported webs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">import_setting</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">-import X</span></span><span class="comment">: where to find imported webs</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">inweb_instructions</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure inweb_instructions is accessed in 1/pc and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Reading the command line. </b>The dull work of this is done by the Foundation module: all we need to do is
to enumerate constants for the Inweb-specific command line switches, and
@ -153,7 +153,7 @@ then declare them.
<span class="plain-syntax"> </span><span class="identifier-syntax">args</span><span class="plain-syntax">.</span><span class="element-syntax">test_language_setting</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">args</span><span class="plain-syntax">.</span><span class="element-syntax">test_language_on_setting</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-cnf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_2"></a><b>&#167;2.2. </b>The CommandLine section of Foundation needs to be told what command-line
switches we want, other than the standard set (such as <code class="display"><span class="extract-syntax">-help</span></code>) which it
switches we want, other than the standard set (such as <span class="extract"><span class="extract-syntax">-help</span></span>) which it
provides automatically.
</p>
@ -293,7 +293,7 @@ provides automatically.
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"explain what inweb is doing"</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-cla.html#SP5" class="function-link"><span class="function-syntax">CommandLine::declare_switch</span></a><span class="plain-syntax">(</span><span class="constant-syntax">IMPORT_FROM_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"import-from"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"specify that imported modules are at pathname X"</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-cnf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Foundation calls this on any <code class="display"><span class="extract-syntax">-switch</span></code> argument read:
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-cnf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Foundation calls this on any <span class="extract"><span class="extract-syntax">-switch</span></span> argument read:
</p>
<pre class="displayed-code all-displayed-code">
@ -424,8 +424,8 @@ location and its navigational aids.
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>Foundation calls this routine on any command-line argument which is
neither a switch (like <code class="display"><span class="extract-syntax">-weave</span></code>), nor an argument for a switch (like
the <code class="display"><span class="extract-syntax">X</span></code> in <code class="display"><span class="extract-syntax">-weave-as X</span></code>).
neither a switch (like <span class="extract"><span class="extract-syntax">-weave</span></span>), nor an argument for a switch (like
the <span class="extract"><span class="extract-syntax">X</span></span> in <span class="extract"><span class="extract-syntax">-weave-as X</span></span>).
</p>
<pre class="displayed-code all-displayed-code">
@ -438,8 +438,8 @@ the <code class="display"><span class="extract-syntax">X</span></code> in <code
<span class="plain-syntax"> </span><span class="identifier-syntax">args</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">chosen_web</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-pth.html#SP5" class="function-link"><span class="function-syntax">Pathnames::from_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">opt</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><a href="1-cnf.html#SP6" class="function-link"><span class="function-syntax">Configuration::set_range</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">args</span><span class="plain-syntax">, </span><span class="identifier-syntax">opt</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Here we read a range. The special ranges <code class="display"><span class="extract-syntax">index</span></code>, <code class="display"><span class="extract-syntax">chapters</span></code> and <code class="display"><span class="extract-syntax">sections</span></code>
are converted into swarm settings instead. <code class="display"><span class="extract-syntax">all</span></code> is simply an alias for <code class="display"><span class="extract-syntax">0</span></code>.
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Here we read a range. The special ranges <span class="extract"><span class="extract-syntax">index</span></span>, <span class="extract"><span class="extract-syntax">chapters</span></span> and <span class="extract"><span class="extract-syntax">sections</span></span>
are converted into swarm settings instead. <span class="extract"><span class="extract-syntax">all</span></span> is simply an alias for <span class="extract"><span class="extract-syntax">0</span></span>.
Otherwise, a range is a chapter number/letter, or a section range.
</p>

13
docs/inweb/1-pc.html
View file

@ -72,9 +72,9 @@ so the fork in the road is not met until halfway through Inweb's execution.
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>This operation will be applied to a single web, and will apply to the whole
of that web unless we specify otherwise. Subsets of the web are represented by
short pieces of text called "ranges". This can be a section range like
<code class="display"><span class="extract-syntax">2/pine</span></code>, a chapter number like <code class="display"><span class="extract-syntax">12</span></code>, an appendix letter <code class="display"><span class="extract-syntax">A</span></code> or the
preliminaries block <code class="display"><span class="extract-syntax">P</span></code>, the special chapter <code class="display"><span class="extract-syntax">S</span></code> for the "Sections" chapter
of an unchaptered web, or the special value <code class="display"><span class="extract-syntax">0</span></code> to mean the entire web (which
<span class="extract"><span class="extract-syntax">2/pine</span></span>, a chapter number like <span class="extract"><span class="extract-syntax">12</span></span>, an appendix letter <span class="extract"><span class="extract-syntax">A</span></span> or the
preliminaries block <span class="extract"><span class="extract-syntax">P</span></span>, the special chapter <span class="extract"><span class="extract-syntax">S</span></span> for the "Sections" chapter
of an unchaptered web, or the special value <span class="extract"><span class="extract-syntax">0</span></span> to mean the entire web (which
is the default).
</p>
@ -95,7 +95,7 @@ one after another.
enables it to find its configuration file, the macros file, and so on.
Unless told otherwise on the command line, we'll assume Inweb is present
in the current working directory. The "materials" will then be in a further
subfolder called <code class="display"><span class="extract-syntax">Materials</span></code>.
subfolder called <span class="extract"><span class="extract-syntax">Materials</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -265,7 +265,7 @@ output, but needs to be part of the web since it's essential to an understanding
of the whole system.
</p>
<p class="inwebparagraph">In this section we determine <code class="display"><span class="extract-syntax">tn</span></code>, the target number wanted, and <code class="display"><span class="extract-syntax">tangle_to</span></code>,
<p class="inwebparagraph">In this section we determine <span class="extract"><span class="extract-syntax">tn</span></span>, the target number wanted, and <span class="extract"><span class="extract-syntax">tangle_to</span></span>,
the filename of the tangled code to write. This may have been set at the command
line , but otherwise we impose a sensible choice based on the target.
</p>
@ -310,7 +310,7 @@ which for many small webs will be the entire thing.
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tangle_leaf</span><span class="plain-syntax">, </span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::get_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Title"</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::concatenate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tangle_leaf</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">main_language</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">file_extension</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-pc.html#SP7_4_2">&#167;7.4.2</a>.</li></ul><p class="inwebparagraph"><a id="SP7_4_2_2"></a><b>&#167;7.4.2.2. </b>If someone tangles, say, <code class="display"><span class="extract-syntax">2/eg</span></code> then the default filename is "Example Section".
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-pc.html#SP7_4_2">&#167;7.4.2</a>.</li></ul><p class="inwebparagraph"><a id="SP7_4_2_2"></a><b>&#167;7.4.2.2. </b>If someone tangles, say, <span class="extract"><span class="extract-syntax">2/eg</span></span> then the default filename is "Example Section".
</p>
@ -354,7 +354,6 @@ which for many small webs will be the entire thing.
<span class="plain-syntax"> </span><a href="1-ts.html#SP2" class="function-link"><span class="function-syntax">Swarm::weave_subset</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">chosen_range</span><span class="plain-syntax">, </span><span class="identifier-syntax">shall_we_open</span><span class="plain-syntax">, </span><span class="identifier-syntax">tag</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to_setting</span><span class="plain-syntax">, </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_into_setting</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">breadcrumb_setting</span><span class="plain-syntax">, </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">navigation_setting</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::copy_payloads_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="1-ts.html#SP1" class="function-link"><span class="function-syntax">Swarm::weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">chosen_range</span><span class="plain-syntax">, </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">swarm_mode</span><span class="plain-syntax">, </span><span class="identifier-syntax">tag</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to_setting</span><span class="plain-syntax">, </span><span class="identifier-syntax">ins</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_into_setting</span><span class="plain-syntax">,</span>

269
docs/inweb/1-ptt.html
View file

@ -48,40 +48,43 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="1-ptt.html#SP1">&#167;1. Reading in</a></li><li><a href="1-ptt.html#SP5">&#167;5. Obtaining files</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Reading in. </b>Patterns are stored as directories in the file system, and are identified by
names such as <code class="display"><span class="extract-syntax">HTML</span></code>. On request, we need to find the directory corresponding
names such as <span class="extract"><span class="extract-syntax">HTML</span></span>. On request, we need to find the directory corresponding
to such a name, and to read it in. This structure holds the result:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern_name</span><span class="plain-syntax">; </span><span class="comment"> such as </span><code class="display"><span class="extract-syntax">HTML</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern_name</span><span class="plain-syntax">; </span><span class="comment"> such as </span><span class="extract"><span class="extract-syntax">HTML</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern_location</span><span class="plain-syntax">; </span><span class="comment"> the directory</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">based_on</span><span class="plain-syntax">; </span><span class="comment"> inherit from which other pattern?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_format</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern_format</span><span class="plain-syntax">; </span><span class="comment"> such as </span><code class="display"><span class="extract-syntax">DVI</span></code><span class="comment">: the desired final format</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugins</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">weave_plugin</span></code><span class="comment">: any extras needed</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colour_schemes</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">colour_scheme</span></code><span class="comment">: any extras needed</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">payloads</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">text_stream</span></code><span class="comment">: leafnames of associated files</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">up_payloads</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">text_stream</span></code><span class="comment">: leafnames of associated files</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_format</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern_format</span><span class="plain-syntax">; </span><span class="comment"> such as </span><span class="extract"><span class="extract-syntax">DVI</span></span><span class="comment">: the desired final format</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugins</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">weave_plugin</span></span><span class="comment">: any extras needed</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colour_schemes</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">colour_scheme</span></span><span class="comment">: any extras needed</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tex_command</span><span class="plain-syntax">; </span><span class="comment"> shell command to use for </span><code class="display"><span class="extract-syntax">tex</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pdftex_command</span><span class="plain-syntax">; </span><span class="comment"> shell command to use for </span><code class="display"><span class="extract-syntax">pdftex</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">open_command</span><span class="plain-syntax">; </span><span class="comment"> shell command to use for </span><code class="display"><span class="extract-syntax">open</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">mathematics_plugin</span><span class="plain-syntax">; </span><span class="comment"> name only, not a </span><span class="extract"><span class="extract-syntax">weave_pattern *</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">footnotes_plugin</span><span class="plain-syntax">; </span><span class="comment"> name only, not a </span><span class="extract"><span class="extract-syntax">weave_pattern *</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tex_command</span><span class="plain-syntax">; </span><span class="comment"> shell command to use for </span><span class="extract"><span class="extract-syntax">tex</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pdftex_command</span><span class="plain-syntax">; </span><span class="comment"> shell command to use for </span><span class="extract"><span class="extract-syntax">pdftex</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">open_command</span><span class="plain-syntax">; </span><span class="comment"> shell command to use for </span><span class="extract"><span class="extract-syntax">open</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">embed_CSS</span><span class="plain-syntax">; </span><span class="comment"> embed CSS directly into any HTML files made?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">hierarchical</span><span class="plain-syntax">; </span><span class="comment"> weave as one part of a collection of woven webs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">show_abbrevs</span><span class="plain-syntax">; </span><span class="comment"> show section range abbreviations in the weave?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">number_sections</span><span class="plain-syntax">; </span><span class="comment"> insert section numbers into the weave?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">default_range</span><span class="plain-syntax">; </span><span class="comment"> for example, </span><code class="display"><span class="extract-syntax">sections</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">default_range</span><span class="plain-syntax">; </span><span class="comment"> for example, </span><span class="extract"><span class="extract-syntax">sections</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">patterned_for</span><span class="plain-syntax">; </span><span class="comment"> the web which caused this to be read in</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">commands</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">name_command_given</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure weave_pattern is accessed in 1/pc, 1/ts, 3/ti, 5/fm, 5/tf, 5/wp, 5/rtt and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>When a given web needs a pattern with a given name, this is where it comes.
</pre><ul class="endnotetexts"><li>The structure weave_pattern is accessed in 1/pc, 1/ts, 5/fm, 5/tf, 5/hf, 5/wp, 5/rtt and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>When a given web needs a pattern with a given name, this is where it comes.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::find</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>Patterns::find</b>:<br><a href="1-ptt.html#SP3_1">&#167;3.1</a>, Program Control - <a href="1-pc.html#SP7_4_3">&#167;7.4.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::find</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>Patterns::find</b>:<br><a href="1-ptt.html#SP3">&#167;3</a>, Program Control - <a href="1-pc.html#SP7_4_3">&#167;7.4.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Initialise the pattern structure</span> <span class="named-paragraph-number">2.1</span>&gt;<span class="plain-syntax">;</span>
@ -98,18 +101,18 @@ to such a name, and to read it in. This structure holds the result:
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_location</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">plugins</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">colour_schemes</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">colour_scheme</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">payloads</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">up_payloads</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hierarchical</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">patterned_for</span><span class="plain-syntax"> = </span><span class="identifier-syntax">W</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number_sections</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">footnotes_plugin</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">mathematics_plugin</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_range</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"0"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tex_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"tex"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pdftex_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"pdftex"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">open_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"open"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">commands</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name_command_given</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_2"></a><b>&#167;2.2. </b><code class="display">
&lt;<span class="named-paragraph-defn">Locate the pattern directory</span> <span class="named-paragraph-number">2.2</span>&gt; =
</code></p>
@ -146,124 +149,106 @@ to such a name, and to read it in. This structure holds the result:
<span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">, </span><a href="1-ptt.html#SP3" class="function-link"><span class="function-syntax">Patterns::scan_pattern_line</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">wp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_text</span></a><span class="plain-syntax">(</span><span class="string-syntax">"pattern did not specify a format"</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name_command_given</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_text</span></a><span class="plain-syntax">(</span><span class="string-syntax">"pattern did not name itself at the top"</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The Foundation module provides a standard way to scan text files line by
line, and this is used to send each line in the <code class="display"><span class="extract-syntax">pattern.txt</span></code> file to the
line, and this is used to send each line in the <span class="extract"><span class="extract-syntax">pattern.txt</span></span> file to the
following routine:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::scan_pattern_line</span><button class="popup" onclick="togglePopup('usagePopup2')">...<span class="popuptext" id="usagePopup2">Usage of <b>Patterns::scan_pattern_line</b>:<br><a href="1-ptt.html#SP2_3">&#167;2.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">X</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">X</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP24" class="function-link"><span class="function-syntax">Str::trim_white_space</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">); </span><span class="comment"> ignore trailing space</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">; </span><span class="comment"> ignore blank lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get_first_char</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">) == </span><span class="character-syntax">'#'</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">; /* </span><span class="identifier-syntax">lines</span><span class="plain-syntax"> </span><span class="identifier-syntax">opening</span><span class="plain-syntax"> </span><span class="identifier-syntax">with</span><span class="plain-syntax"> |#| </span><span class="identifier-syntax">are</span><span class="plain-syntax"> </span><span class="identifier-syntax">comments</span><span class="plain-syntax"> */</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">commands</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *from (%c+)"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is a from command</span> <span class="named-paragraph-number">3.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *(%c+?) = (%c+)"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is an X = Y command</span> <span class="named-paragraph-number">3.2</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *embed css *"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is an embed CSS command</span> <span class="named-paragraph-number">3.3</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *hierarchical *"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is a hierarchical command</span> <span class="named-paragraph-number">3.4</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *plugin (%c+)"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is a plugin command</span> <span class="named-paragraph-number">3.5</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *use (%c+)"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is a use command</span> <span class="named-paragraph-number">3.6</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *use-up (%c+)"</span><span class="plain-syntax">)) </span>&lt;<span class="named-paragraph">This is a use-up command</span> <span class="named-paragraph-number">3.7</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *%C%c*"</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unrecognised pattern command"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3_1"></a><b>&#167;3.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">This is a from command</span> <span class="named-paragraph-number">3.1</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP2" class="function-link"><span class="function-syntax">Patterns::find</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">patterned_for</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_2"></a><b>&#167;3.2. </b><code class="display">
&lt;<span class="named-paragraph-defn">This is an X = Y command</span> <span class="named-paragraph-number">3.2</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"format"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax"> = </span><a href="5-fm.html#SP1" class="function-link"><span class="function-syntax">Formats::find_by_name</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"abbrevs"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::yes_or_no</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1], </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"numbered"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number_sections</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::yes_or_no</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1], </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"default-range"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_range</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"tex-command"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tex_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"pdftex-command"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pdftex_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"open-command"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">open_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::data_exists</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">patterned_for</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0])) ||</span>
<span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"Booklet Title"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">patterned_for</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c+) *: *(%c+?)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], *</span><span class="identifier-syntax">value</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"name"</span><span class="plain-syntax">)) &amp;&amp; (</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">commands</span><span class="plain-syntax"> == </span><span class="constant-syntax">1</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr2</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">, </span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c+?) based on (%c+)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::ne_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_name</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"wrong pattern name"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP2" class="function-link"><span class="function-syntax">Patterns::find</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">patterned_for</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr2</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax"> = </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax"> = </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number_sections</span><span class="plain-syntax"> = </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number_sections</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_range</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_range</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">mathematics_plugin</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">mathematics_plugin</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">footnotes_plugin</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">footnotes_plugin</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::ne_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_name</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"wrong pattern name"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name_command_given</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"plugin"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::plugin_name</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugin</span><span class="plain-syntax"> = </span><a href="5-wp.html#SP2" class="function-link"><span class="function-syntax">WeavePlugins::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">plugin</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax">, </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">plugins</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"format"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax"> = </span><a href="5-fm.html#SP1" class="function-link"><span class="function-syntax">Formats::find_by_name</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"embed CSS"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::yes_or_no</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"number sections"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number_sections</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::yes_or_no</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"default range"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">default_range</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"mathematics plugin"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">mathematics_plugin</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::plugin_name</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"footnotes plugin"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">footnotes_plugin</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP4" class="function-link"><span class="function-syntax">Patterns::plugin_name</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TeX command"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tex_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"PDFTeX command"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pdftex_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"open command"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">open_command</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">value</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"bibliographic data"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr2</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">, </span><span class="identifier-syntax">value</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c+?) = (%c+)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/8-bdfw.html#SP7" class="function-link"><span class="function-syntax">Bibliographic::set_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">patterned_for</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr2</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">mr2</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"syntax is 'bibliographic data: X = Y'"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unrecognised pattern command"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PRINT</span><span class="plain-syntax">(</span><span class="string-syntax">"Setting: %S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"no such pattern setting"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unrecognised pattern command"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_3"></a><b>&#167;3.3. </b><code class="display">
&lt;<span class="named-paragraph-defn">This is an embed CSS command</span> <span class="named-paragraph-number">3.3</span>&gt; =
</code></p>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_4"></a><b>&#167;3.4. </b><code class="display">
&lt;<span class="named-paragraph-defn">This is a hierarchical command</span> <span class="named-paragraph-number">3.4</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hierarchical</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_5"></a><b>&#167;3.5. </b>"Plugins" here refer to <a href="5-wp.html" class="internal">Weave Plugins</a>.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="named-paragraph-defn">This is a plugin command</span> <span class="named-paragraph-number">3.5</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugin</span><span class="plain-syntax"> = </span><a href="5-wp.html#SP2" class="function-link"><span class="function-syntax">WeavePlugins::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">plugin</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax">, </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">plugins</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_6"></a><b>&#167;3.6. </b>"Payloads" are associated files such as images which may be needed for an
HTML weave to look right. We identify them here only by leafname: their
actual location will depend on where the pattern directory is.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="named-paragraph-defn">This is a use command</span> <span class="named-paragraph-number">3.6</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leafname</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">, </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">payloads</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_7"></a><b>&#167;3.7. </b><code class="display">
&lt;<span class="named-paragraph-defn">This is a use-up command</span> <span class="named-paragraph-number">3.7</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leafname</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">, </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">up_payloads</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="1-ptt.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::yes_or_no</span><button class="popup" onclick="togglePopup('usagePopup3')">...<span class="popuptext" id="usagePopup3">Usage of <b>Patterns::yes_or_no</b>:<br><a href="1-ptt.html#SP3_2">&#167;3.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::yes_or_no</span><button class="popup" onclick="togglePopup('usagePopup3')">...<span class="popuptext" id="usagePopup3">Usage of <b>Patterns::yes_or_no</b>:<br><a href="1-ptt.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"yes"</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"no"</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"setting must be 'yes' or 'no'"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::plugin_name</span><button class="popup" onclick="togglePopup('usagePopup4')">...<span class="popuptext" id="usagePopup4">Usage of <b>Patterns::plugin_name</b>:<br><a href="1-ptt.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%i+)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"none"</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"plugin names must be single alphanumeric words"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">arg</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Obtaining files. </b>Patterns provide not merely some configuration settings (above): they also
provide template or style files of various kinds. When Inweb wants to find
a pattern file with a given leafname, it looks for it in the pattern
@ -276,7 +261,7 @@ from each other then this routine will lock up into an infinite loop.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::obtain_filename</span><button class="popup" onclick="togglePopup('usagePopup4')">...<span class="popuptext" id="usagePopup4">Usage of <b>Patterns::obtain_filename</b>:<br><a href="1-ptt.html#SP7">&#167;7</a>, The Swarm - <a href="1-ts.html#SP4">&#167;4</a>&lt;br&gt;The Indexer - <a href="3-ti.html#SP1">&#167;1</a>, <a href="3-ti.html#SP2">&#167;2</a>, <a href="3-ti.html#SP2_1_3">&#167;2.1.3</a>, <a href="3-ti.html#SP6_1">&#167;6.1</a>&lt;br&gt;TeX Format - <a href="5-tf.html#SP2_1_1">&#167;2.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::obtain_filename</span><button class="popup" onclick="togglePopup('usagePopup5')">...<span class="popuptext" id="usagePopup5">Usage of <b>Patterns::obtain_filename</b>:<br>The Swarm - <a href="1-ts.html#SP4">&#167;4</a>&lt;br&gt;The Indexer - <a href="3-ti.html#SP1">&#167;1</a>, <a href="3-ti.html#SP2_1_2">&#167;2.1.2</a>&lt;br&gt;TeX Format - <a href="5-tf.html#SP2_1_1">&#167;2.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP21" class="function-link"><span class="function-syntax">Str::prefix_eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"../"</span><span class="plain-syntax">, </span><span class="constant-syntax">3</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP25" class="function-link"><span class="function-syntax">Str::delete_first_character</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP25" class="function-link"><span class="function-syntax">Str::delete_first_character</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
@ -291,7 +276,7 @@ from each other then this routine will lock up into an infinite loop.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::find_asset</span><button class="popup" onclick="togglePopup('usagePopup5')">...<span class="popuptext" id="usagePopup5">Usage of <b>Patterns::find_asset</b>:<br>HTML Formats - <a href="5-hf.html#SP9">&#167;9</a>, <a href="5-hf.html#SP15">&#167;15</a>&lt;br&gt;Weave Plugins - <a href="5-wp.html#SP4">&#167;4</a>, <a href="5-wp.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dirname</span><span class="plain-syntax">,</span>
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Patterns::find_asset</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>Patterns::find_asset</b>:<br>HTML Formats - <a href="5-hf.html#SP9">&#167;9</a>, <a href="5-hf.html#SP15">&#167;15</a>&lt;br&gt;Weave Plugins - <a href="5-wp.html#SP4">&#167;4</a>, <a href="5-wp.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dirname</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax"> = </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">; </span><span class="identifier-syntax">wp</span><span class="plain-syntax">; </span><span class="identifier-syntax">wp</span><span class="plain-syntax"> = </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-pth.html#SP4" class="function-link"><span class="function-syntax">Pathnames::down</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_location</span><span class="plain-syntax">, </span><span class="identifier-syntax">dirname</span><span class="plain-syntax">);</span>
@ -300,31 +285,7 @@ from each other then this routine will lock up into an infinite loop.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>When we eventually want to deal with the <code class="display"><span class="extract-syntax">use P</span></code> commands, which call
for payloads to be copied into weave, we make good use of the above:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::copy_payloads_into_weave</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>Patterns::copy_payloads_into_weave</b>:<br>Program Control - <a href="1-pc.html#SP7_4_3">&#167;7.4.3</a>&lt;br&gt;The Swarm - <a href="1-ts.html#SP4">&#167;4</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">payloads</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP5" class="function-link"><span class="function-syntax">Patterns::obtain_filename</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rel</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP2" class="function-link"><span class="function-syntax">Filenames::in</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/5-ee.html#SP5" class="function-link"><span class="function-syntax">Epub::note_image</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">, </span><span class="identifier-syntax">rel</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">up_payloads</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP5" class="function-link"><span class="function-syntax">Patterns::obtain_filename</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::copy_up_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rel</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP2" class="function-link"><span class="function-syntax">Filenames::in</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/5-ee.html#SP5" class="function-link"><span class="function-syntax">Epub::note_image</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">, </span><span class="identifier-syntax">rel</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b></p>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">css_file_transformation</span><span class="plain-syntax"> {</span>
@ -332,7 +293,7 @@ for payloads to be copied into weave, we make good use of the above:
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">trans</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">css_file_transformation</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::copy_file_into_weave</span><button class="popup" onclick="togglePopup('usagePopup7')">...<span class="popuptext" id="usagePopup7">Usage of <b>Patterns::copy_file_into_weave</b>:<br><a href="1-ptt.html#SP7">&#167;7</a>, HTML Formats - <a href="5-hf.html#SP5_11">&#167;5.11</a>&lt;br&gt;Weave Plugins - <a href="5-wp.html#SP5">&#167;5</a>, <a href="5-wp.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">trans</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::copy_file_into_weave</span><button class="popup" onclick="togglePopup('usagePopup7')">...<span class="popuptext" id="usagePopup7">Usage of <b>Patterns::copy_file_into_weave</b>:<br>HTML Formats - <a href="5-hf.html#SP5_11">&#167;5.11</a>&lt;br&gt;Weave Plugins - <a href="5-wp.html#SP5_1">&#167;5.1</a>, <a href="5-wp.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">trans</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">redirect_weaves_to</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">H</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><a href="2-tr.html#SP7" class="function-link"><span class="function-syntax">Reader::woven_folder</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax">) </span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><span class="identifier-syntax">P</span><span class="plain-syntax">;</span>
@ -345,12 +306,12 @@ for payloads to be copied into weave, we make good use of the above:
<span class="plain-syntax"> </span><span class="identifier-syntax">cft</span><span class="plain-syntax">.</span><span class="element-syntax">OUT</span><span class="plain-syntax"> = &amp;</span><span class="identifier-syntax">css_S</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cft</span><span class="plain-syntax">.</span><span class="element-syntax">trans</span><span class="plain-syntax"> = </span><span class="identifier-syntax">trans</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-tf.html#SP5" class="function-link"><span class="function-syntax">TextFiles::read</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">, </span><span class="string-syntax">"can't open CSS file"</span><span class="plain-syntax">, </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::transform_CSS</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">cft</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::transform_CSS</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">cft</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">cft</span><span class="plain-syntax">.</span><span class="element-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><a href="../foundation-module/3-shl.html#SP3" class="function-link"><span class="function-syntax">Shell::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">H</span><span class="plain-syntax">, </span><span class="string-syntax">""</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::transform_CSS</span><button class="popup" onclick="togglePopup('usagePopup8')">...<span class="popuptext" id="usagePopup8">Usage of <b>Patterns::transform_CSS</b>:<br>none</span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">X</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::transform_CSS</span><button class="popup" onclick="togglePopup('usagePopup8')">...<span class="popuptext" id="usagePopup8">Usage of <b>Patterns::transform_CSS</b>:<br>Weave Plugins - <a href="5-wp.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">X</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">css_file_transformation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cft</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">css_file_transformation</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">X</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">cft</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">OUT</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
@ -368,18 +329,10 @@ for payloads to be copied into weave, we make good use of the above:
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">spanned</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::copy_up_file_into_weave</span><button class="popup" onclick="togglePopup('usagePopup9')">...<span class="popuptext" id="usagePopup9">Usage of <b>Patterns::copy_up_file_into_weave</b>:<br><a href="1-ptt.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">redirect_weaves_to</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">H</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><a href="2-tr.html#SP7" class="function-link"><span class="function-syntax">Reader::woven_folder</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-pth.html#SP7" class="function-link"><span class="function-syntax">Pathnames::up</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">H</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax">) </span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><span class="identifier-syntax">P</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-shl.html#SP3" class="function-link"><span class="function-syntax">Shell::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">H</span><span class="plain-syntax">, </span><span class="string-syntax">""</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure css_file_transformation is accessed in 5/ptf, 5/tf, 5/hf, 5/df, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b></p>
</pre><ul class="endnotetexts"><li>The structure css_file_transformation is accessed in 5/ptf, 5/tf, 5/hf, 5/df, 5/wp, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::include_plugins</span><button class="popup" onclick="togglePopup('usagePopup10')">...<span class="popuptext" id="usagePopup10">Usage of <b>Patterns::include_plugins</b>:<br>The Indexer - <a href="3-ti.html#SP2_1">&#167;2.1</a>, <a href="3-ti.html#SP6_1_8_4">&#167;6.1.8.4</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Patterns::include_plugins</span><button class="popup" onclick="togglePopup('usagePopup9')">...<span class="popuptext" id="usagePopup9">Usage of <b>Patterns::include_plugins</b>:<br>The Indexer - <a href="3-ti.html#SP2_1">&#167;2.1</a>, <a href="3-ti.html#SP6_1_8_4">&#167;6.1.8.4</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax"> = </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">; </span><span class="identifier-syntax">p</span><span class="plain-syntax">; </span><span class="identifier-syntax">p</span><span class="plain-syntax"> = </span><span class="identifier-syntax">p</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">plugins</span><span class="plain-syntax">)</span>

19
docs/inweb/1-ts.html
View file

@ -55,8 +55,8 @@ resulting flurry a "swarm", like the glittering cloud of locusts in the title
of Chapter 25 of "On the Banks of Plum Creek".
</p>
<p class="inwebparagraph">This routine is called with mode <code class="display"><span class="extract-syntax">SWARM_SECTIONS_SWM</span></code>, <code class="display"><span class="extract-syntax">SWARM_CHAPTERS_SWM</span></code> or
<code class="display"><span class="extract-syntax">SWARM_INDEX_SWM</span></code>, so in a non-swarming run it isn't called at all.
<p class="inwebparagraph">This routine is called with mode <span class="extract"><span class="extract-syntax">SWARM_SECTIONS_SWM</span></span>, <span class="extract"><span class="extract-syntax">SWARM_CHAPTERS_SWM</span></span> or
<span class="extract"><span class="extract-syntax">SWARM_INDEX_SWM</span></span>, so in a non-swarming run it isn't called at all.
</p>
<pre class="displayed-code all-displayed-code">
@ -119,13 +119,13 @@ the call comes from Program Control).
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">; </span><span class="comment"> which pattern is to be followed</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_to</span><span class="plain-syntax">; </span><span class="comment"> where to put it</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_format</span><span class="plain-syntax"> *</span><span class="identifier-syntax">format</span><span class="plain-syntax">; </span><span class="comment"> plain text, say, or HTML</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cover_sheet_to_use</span><span class="plain-syntax">; </span><span class="comment"> leafname of the copy, or </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> for no cover</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cover_sheet_to_use</span><span class="plain-syntax">; </span><span class="comment"> leafname of the copy, or </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> for no cover</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">post_processing_results</span><span class="plain-syntax">; </span><span class="comment"> optional typesetting diagnostics after running through</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">self_contained</span><span class="plain-syntax">; </span><span class="comment"> make a self-contained file if possible</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">breadcrumbs</span><span class="plain-syntax">; </span><span class="comment"> non-standard breadcrumb trail, if any</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">navigation</span><span class="plain-syntax">; </span><span class="comment"> navigation links, or </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> if not supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugins</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">weave_plugin</span></code><span class="comment">: these are for HTML extensions</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colour_schemes</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">colour_scheme</span></code><span class="comment">: these are for HTML</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">navigation</span><span class="plain-syntax">; </span><span class="comment"> navigation links, or </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> if not supplied</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugins</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">weave_plugin</span></span><span class="comment">: these are for HTML extensions</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colour_schemes</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">colour_scheme</span></span><span class="comment">: these are for HTML</span>
<span class="plain-syntax"> </span><span class="comment"> used for workspace during an actual weave:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">current_weave_line</span><span class="plain-syntax">;</span>
@ -288,8 +288,8 @@ and details of any cover-sheet to use.
<span class="plain-syntax"> </span><a href="5-wp.html#SP6" class="function-link"><span class="function-syntax">WeavePlugins::include_colour_scheme</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">cs</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>After every swarm, we rebuild the index. We first try for a template called
<code class="display"><span class="extract-syntax">chaptered-index.html</span></code> or <code class="display"><span class="extract-syntax">unchaptered-index.html</span></code>, then fall back on a
generic <code class="display"><span class="extract-syntax">index.html</span></code> if those aren't available in the current pattern.
<span class="extract"><span class="extract-syntax">chaptered-index.html</span></span> or <span class="extract"><span class="extract-syntax">unchaptered-index.html</span></span>, then fall back on a
generic <span class="extract"><span class="extract-syntax">index.html</span></span> if those aren't available in the current pattern.
</p>
<pre class="displayed-code all-displayed-code">
@ -311,12 +311,11 @@ generic <code class="display"><span class="extract-syntax">index.html</span></co
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unable to write contents file"</span><span class="plain-syntax">, </span><span class="identifier-syntax">Contents</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="../foundation-module/5-ee.html#SP5" class="function-link"><span class="function-syntax">Epub::note_page</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">, </span><span class="identifier-syntax">Contents</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Index"</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"index"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Contents</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Contents</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PRINT</span><span class="plain-syntax">(</span><span class="string-syntax">"[Index file: %f]\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">Contents</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP3" class="function-link"><span class="function-syntax">Indexer::incorporate_template</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">range</span><span class="plain-syntax">, </span><span class="identifier-syntax">INF</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">nav</span><span class="plain-syntax">, </span><span class="identifier-syntax">crumbs</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::copy_payloads_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><hr class="tocbar">
<ul class="toc"><li><a href="1-cnf.html">Back to 'Configuration'</a></li><li><a href="1-ptt.html">Continue with 'Patterns'</a></li></ul><hr class="tocbar">

14
docs/inweb/2-ec.html
View file

@ -46,9 +46,9 @@ function togglePopup(material_id) {
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#2">Chapter 2: Parsing a Web</a></li><li><b>Enumerated Constants</b></li></ul><p class="purpose">To define sequentially numbered values for families of constants.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>The idea here is that each enumeration set is a sequence of named constants
with a given postfix: for example, <code class="display"><span class="extract-syntax">HARRY_ST</span></code>, <code class="display"><span class="extract-syntax">NEVILLE_ST</span></code>, <code class="display"><span class="extract-syntax">ANGELINA_ST</span></code>
form the <code class="display"><span class="extract-syntax">*_ST</span></code> set. By definition, the postfix part is the portion of the
name following the final underscore, so in this case <code class="display"><span class="extract-syntax">ST</span></code>.
with a given postfix: for example, <span class="extract"><span class="extract-syntax">HARRY_ST</span></span>, <span class="extract"><span class="extract-syntax">NEVILLE_ST</span></span>, <span class="extract"><span class="extract-syntax">ANGELINA_ST</span></span>
form the <span class="extract"><span class="extract-syntax">*_ST</span></span> set. By definition, the postfix part is the portion of the
name following the final underscore, so in this case <span class="extract"><span class="extract-syntax">ST</span></span>.
</p>
<p class="inwebparagraph">Each set of constants begins at a given value (typically 0) and then
@ -76,7 +76,7 @@ compare all against all:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">es</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The following is called when an enumeration is found. If <code class="display"><span class="extract-syntax">from</span></code> has a
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The following is called when an enumeration is found. If <span class="extract"><span class="extract-syntax">from</span></span> has a
sensible value, this is the start of a new enumeration set; otherwise it's
a further constant in what ought to be an existing set.
</p>
@ -92,7 +92,7 @@ a further constant in what ought to be an existing set.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pf</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">es</span><span class="plain-syntax">) </span><span class="identifier-syntax">es</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_observed_at</span><span class="plain-syntax"> = </span><span class="identifier-syntax">L</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3_1"></a><b>&#167;3.1. </b>So for instance <code class="display"><span class="extract-syntax">HARRY_ST</span></code> to <code class="display"><span class="extract-syntax">ST</span></code>:
</pre><p class="inwebparagraph"><a id="SP3_1"></a><b>&#167;3.1. </b>So for instance <span class="extract"><span class="extract-syntax">HARRY_ST</span></span> to <span class="extract"><span class="extract-syntax">ST</span></span>:
</p>
@ -143,8 +143,8 @@ a further constant in what ought to be an existing set.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%d"</span><span class="plain-syntax">, </span><span class="identifier-syntax">es</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">first_value</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">es</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stub</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">")"</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-ec.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>For each set, a further constant is defined to give the range; for example,
we would have <code class="display"><span class="extract-syntax">NO_DEFINED_ST_VALUES</span></code> set to 3. This is notionally placed in
the code at the last line on which an <code class="display"><span class="extract-syntax">*_ST</span></code> value was defined.
we would have <span class="extract"><span class="extract-syntax">NO_DEFINED_ST_VALUES</span></span> set to 3. This is notionally placed in
the code at the last line on which an <span class="extract"><span class="extract-syntax">*_ST</span></span> value was defined.
</p>
<pre class="displayed-code all-displayed-code">

54
docs/inweb/2-lc.html
View file

@ -52,7 +52,7 @@ structure of chapters, sections and eventually paragraphs. But before we do
that, we'll define the structure used to store a single line of the web.
</p>
<p class="inwebparagraph">Because Inweb markup makes use of the special characters <code class="display"><span class="extract-syntax">@</span></code> and <code class="display"><span class="extract-syntax">=</span></code> as
<p class="inwebparagraph">Because Inweb markup makes use of the special characters <span class="extract"><span class="extract-syntax">@</span></span> and <span class="extract"><span class="extract-syntax">=</span></span> as
dividers, but only in column 1, the important divisions between material
all effectively occur at line boundaries &mdash; this is a major point of
difference with, for example, CWEB, for which the source is just a stream
@ -67,12 +67,12 @@ correspond to one of these:
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text_operand</span><span class="plain-syntax">; </span><span class="comment"> meaning depends on category</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text_operand2</span><span class="plain-syntax">; </span><span class="comment"> meaning depends on category</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">category</span><span class="plain-syntax">; </span><span class="comment"> what sort of line this is: an </span><code class="display"><span class="extract-syntax">*_LCAT</span></code><span class="comment"> value</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">command_code</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">COMMAND_LCAT</span></code><span class="comment"> lines: a </span><code class="display"><span class="extract-syntax">*_CMD</span></code><span class="comment"> value</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">default_defn</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">BEGIN_DEFINITION_LCAT</span></code><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">plainer</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">BEGIN_CODE_LCAT</span></code><span class="comment"> lines: suppresses box</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">enable_hyperlinks</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">CODE_BODY_LCAT</span></code><span class="comment"> lines: link URLs in weave</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colour_as</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">TEXT_EXTRACT_LCAT</span></code><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">category</span><span class="plain-syntax">; </span><span class="comment"> what sort of line this is: an </span><span class="extract"><span class="extract-syntax">*_LCAT</span></span><span class="comment"> value</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">command_code</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">COMMAND_LCAT</span></span><span class="comment"> lines: a </span><span class="extract"><span class="extract-syntax">*_CMD</span></span><span class="comment"> value</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">default_defn</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">BEGIN_DEFINITION_LCAT</span></span><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">plainer</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">BEGIN_CODE_LCAT</span></span><span class="comment"> lines: suppresses box</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">enable_hyperlinks</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">CODE_BODY_LCAT</span></span><span class="comment"> lines: link URLs in weave</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">colour_as</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">TEXT_EXTRACT_LCAT</span></span><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">is_commentary</span><span class="plain-syntax">; </span><span class="comment"> flag</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">language_function</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_defined</span><span class="plain-syntax">; </span><span class="comment"> if any C-like function is defined on this line</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">preform_nonterminal</span><span class="plain-syntax"> *</span><span class="identifier-syntax">preform_nonterminal_defined</span><span class="plain-syntax">; </span><span class="comment"> similarly</span>
@ -84,7 +84,7 @@ correspond to one of these:
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">section</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owning_section</span><span class="plain-syntax">; </span><span class="comment"> for interleaved title lines, it's the one about to start</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">next_line</span><span class="plain-syntax">; </span><span class="comment"> within the owning section's linked list</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owning_paragraph</span><span class="plain-syntax">; </span><span class="comment"> for lines falling under paragraphs; </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> if not</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owning_paragraph</span><span class="plain-syntax">; </span><span class="comment"> for lines falling under paragraphs; </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> if not</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">source_line</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure source_line is accessed in 1/pc, 2/tr, 2/tp, 2/pm, 2/ec, 2/pn, 3/ta, 3/tw, 3/twot, 3/tt, 4/taf, 4/lm, 4/as, 4/cl, 4/is, 5/wt, 5/ptf, 5/tf, 5/hf, 5/df, 6/cln and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b></p>
@ -122,40 +122,40 @@ correspond to one of these:
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Categories. </b>The line categories are enumerated as follows. We briefly note what the text
operands (TO and TO2) are set to, if anything: most of the time they're blank.
Note that a few of these categories are needed only for the more cumbersome
version 1 syntax; version 2 removed the need for <code class="display"><span class="extract-syntax">BAR_LCAT</span></code>,
<code class="display"><span class="extract-syntax">INTERFACE_BODY_LCAT</span></code>, and <code class="display"><span class="extract-syntax">INTERFACE_LCAT</span></code>.
version 1 syntax; version 2 removed the need for <span class="extract"><span class="extract-syntax">BAR_LCAT</span></span>,
<span class="extract"><span class="extract-syntax">INTERFACE_BODY_LCAT</span></span>, and <span class="extract"><span class="extract-syntax">INTERFACE_LCAT</span></span>.
</p>
<pre class="definitions">
<span class="definition-keyword">enum</span> <span class="constant-syntax">NO_LCAT</span><span class="plain-syntax"> </span><span class="identifier-syntax">from</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax"> </span><span class="comment"> (used when none has been set as yet)</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BAR_LCAT</span><span class="plain-syntax"> </span><span class="comment"> a bar line </span><code class="display"><span class="extract-syntax">@---------------</span></code><span class="comment">...</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BEGIN_CODE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> an </span><code class="display"><span class="extract-syntax">@c</span></code><span class="comment">, </span><code class="display"><span class="extract-syntax">@e</span></code><span class="comment"> or </span><code class="display"><span class="extract-syntax">@x</span></code><span class="comment"> line below which is code, early code or extract</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BEGIN_DEFINITION_LCAT</span><span class="plain-syntax"> </span><span class="comment"> an </span><code class="display"><span class="extract-syntax">@d</span></code><span class="comment"> definition: TO is term, TO2 is this line's part of defn</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">C_LIBRARY_INCLUDE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> C-like languages only: a </span><code class="display"><span class="extract-syntax">#include</span></code><span class="comment"> for an ANSI C header file</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BAR_LCAT</span><span class="plain-syntax"> </span><span class="comment"> a bar line </span><span class="extract"><span class="extract-syntax">@---------------</span></span><span class="comment">...</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BEGIN_CODE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> an </span><span class="extract"><span class="extract-syntax">@c</span></span><span class="comment">, </span><span class="extract"><span class="extract-syntax">@e</span></span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">@x</span></span><span class="comment"> line below which is code, early code or extract</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BEGIN_DEFINITION_LCAT</span><span class="plain-syntax"> </span><span class="comment"> an </span><span class="extract"><span class="extract-syntax">@d</span></span><span class="comment"> definition: TO is term, TO2 is this line's part of defn</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">C_LIBRARY_INCLUDE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> C-like languages only: a </span><span class="extract"><span class="extract-syntax">#include</span></span><span class="comment"> for an ANSI C header file</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CHAPTER_HEADING_LCAT</span><span class="plain-syntax"> </span><span class="comment"> chapter heading line inserted automatically, not read from web</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CODE_BODY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> the rest of the paragraph under an </span><code class="display"><span class="extract-syntax">@c</span></code><span class="comment"> or </span><code class="display"><span class="extract-syntax">@e</span></code><span class="comment"> or macro definition</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">COMMAND_LCAT</span><span class="plain-syntax"> </span><span class="comment"> a </span><code class="display"><span class="extract-syntax">[[Command]]</span></code><span class="comment"> line, with the operand set to the </span><code class="display"><span class="extract-syntax">*_CMD</span></code><span class="comment"> value</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CODE_BODY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> the rest of the paragraph under an </span><span class="extract"><span class="extract-syntax">@c</span></span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">@e</span></span><span class="comment"> or macro definition</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">COMMAND_LCAT</span><span class="plain-syntax"> </span><span class="comment"> a </span><span class="extract"><span class="extract-syntax">[[Command]]</span></span><span class="comment"> line, with the operand set to the </span><span class="extract"><span class="extract-syntax">*_CMD</span></span><span class="comment"> value</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">COMMENT_BODY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> text following a paragraph header, which is all comment</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CONT_DEFINITION_LCAT</span><span class="plain-syntax"> </span><span class="comment"> subsequent lines of an </span><code class="display"><span class="extract-syntax">@d</span></code><span class="comment"> definition</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">DEFINITIONS_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line holding the </span><code class="display"><span class="extract-syntax">@Definitions:</span></code><span class="comment"> heading</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">END_EXTRACT_LCAT</span><span class="plain-syntax"> </span><span class="comment"> an </span><code class="display"><span class="extract-syntax">=</span></code><span class="comment"> line used to mark the end of an extract</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CONT_DEFINITION_LCAT</span><span class="plain-syntax"> </span><span class="comment"> subsequent lines of an </span><span class="extract"><span class="extract-syntax">@d</span></span><span class="comment"> definition</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">DEFINITIONS_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line holding the </span><span class="extract"><span class="extract-syntax">@Definitions:</span></span><span class="comment"> heading</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">END_EXTRACT_LCAT</span><span class="plain-syntax"> </span><span class="comment"> an </span><span class="extract"><span class="extract-syntax">=</span></span><span class="comment"> line used to mark the end of an extract</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">FOOTNOTE_TEXT_LCAT</span><span class="plain-syntax"> </span><span class="comment"> the opening of the text of a footnote</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">HEADING_START_LCAT</span><span class="plain-syntax"> </span><span class="comment"> </span><code class="display"><span class="extract-syntax">@h</span></code><span class="comment"> paragraph start: TO is title, TO2 is rest of line</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">HEADING_START_LCAT</span><span class="plain-syntax"> </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">@h</span></span><span class="comment"> paragraph start: TO is title, TO2 is rest of line</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">INTERFACE_BODY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line within the interface, under this heading</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">INTERFACE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line holding the </span><code class="display"><span class="extract-syntax">@Interface:</span></code><span class="comment"> heading</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">MACRO_DEFINITION_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line on which a paragraph macro is defined with an </span><code class="display"><span class="extract-syntax">=</span></code><span class="comment"> sign</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PARAGRAPH_START_LCAT</span><span class="plain-syntax"> </span><span class="comment"> simple </span><code class="display"><span class="extract-syntax">@</span></code><span class="comment"> paragraph start: TO is blank, TO2 is rest of line</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">INTERFACE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line holding the </span><span class="extract"><span class="extract-syntax">@Interface:</span></span><span class="comment"> heading</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">MACRO_DEFINITION_LCAT</span><span class="plain-syntax"> </span><span class="comment"> line on which a paragraph macro is defined with an </span><span class="extract"><span class="extract-syntax">=</span></span><span class="comment"> sign</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PARAGRAPH_START_LCAT</span><span class="plain-syntax"> </span><span class="comment"> simple </span><span class="extract"><span class="extract-syntax">@</span></span><span class="comment"> paragraph start: TO is blank, TO2 is rest of line</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PREFORM_GRAMMAR_LCAT</span><span class="plain-syntax"> </span><span class="comment"> InC only: line of Preform grammar</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PREFORM_LCAT</span><span class="plain-syntax"> </span><span class="comment"> InC only: opening line of a Preform nonterminal</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PURPOSE_BODY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> continuation lines of purpose declaration</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PURPOSE_LCAT</span><span class="plain-syntax"> </span><span class="comment"> first line of purpose declaration; TO is rest of line</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">SECTION_HEADING_LCAT</span><span class="plain-syntax"> </span><span class="comment"> section heading line, at top of file</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">SOURCE_DISPLAY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> commentary line beginning </span><code class="display"><span class="extract-syntax">&gt;&gt;</span></code><span class="comment"> for display: TO is display text</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TEXT_EXTRACT_LCAT</span><span class="plain-syntax"> </span><span class="comment"> the rest of the paragraph under an </span><code class="display"><span class="extract-syntax">@x</span></code>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TYPEDEF_LCAT</span><span class="plain-syntax"> </span><span class="comment"> C-like languages only: a </span><code class="display"><span class="extract-syntax">typedef</span></code><span class="comment"> which isn't a structure definition</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">SOURCE_DISPLAY_LCAT</span><span class="plain-syntax"> </span><span class="comment"> commentary line beginning </span><span class="extract"><span class="extract-syntax">&gt;&gt;</span></span><span class="comment"> for display: TO is display text</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TEXT_EXTRACT_LCAT</span><span class="plain-syntax"> </span><span class="comment"> the rest of the paragraph under an </span><span class="extract"><span class="extract-syntax">@x</span></span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TYPEDEF_LCAT</span><span class="plain-syntax"> </span><span class="comment"> C-like languages only: a </span><span class="extract"><span class="extract-syntax">typedef</span></span><span class="comment"> which isn't a structure definition</span>
</pre>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>We want to print these out nicely for the sake of a <code class="display"><span class="extract-syntax">-scan</span></code> analysis run
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>We want to print these out nicely for the sake of a <span class="extract"><span class="extract-syntax">-scan</span></span> analysis run
of Inweb:
</p>

2
docs/inweb/2-pm.html
View file

@ -55,7 +55,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">macro_name</span><span class="plain-syntax">; </span><span class="comment"> usually long, like "Create a paragraph macro here"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">defining_paragraph</span><span class="plain-syntax">; </span><span class="comment"> as printed in small type after the name in any usage</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">defn_start</span><span class="plain-syntax">; </span><span class="comment"> it ends at the end of its defining paragraph</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">macro_usages</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">macro_usage</span></code><span class="comment">: only computed for weaves</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">macro_usages</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">macro_usage</span></span><span class="comment">: only computed for weaves</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">para_macro</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure para_macro is accessed in 2/pn, 3/tw, 3/tt, 5/ptf, 5/tf, 5/hf, 5/df and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Each section has its own linked list of paragraph macros, since the scope for

4
docs/inweb/2-tgs.html
View file

@ -106,8 +106,8 @@ they're stored as a linked list within each paragraph.
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure paragraph_tagging is accessed in 5/wt, 5/hf, 5/df and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>Tags are created simply by being used in taggings. If the tag notation
<code class="display"><span class="extract-syntax">^"History: How tags came about"</span></code> is found, the following is called, and
the tag is <code class="display"><span class="extract-syntax">History</span></code>, the caption "How tags came about".
<span class="extract"><span class="extract-syntax">^"History: How tags came about"</span></span> is found, the following is called, and
the tag is <span class="extract"><span class="extract-syntax">History</span></span>, the caption "How tags came about".
</p>
<pre class="displayed-code all-displayed-code">

56
docs/inweb/2-tp.html
View file

@ -101,9 +101,9 @@ markup syntax, and trying to detect incorrect uses of one within the other.
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">If the section as a whole is tagged, apply that tag to each paragraph in it</span> <span class="named-paragraph-number">1.1.3</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Work out footnote numbering for this section</span> <span class="named-paragraph-number">1.1.4</span>&gt;<span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1">&#167;1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_1"></a><b>&#167;1.1.1. </b>In versiom 2 syntax, the notation for tags was clarified. The tag list
for a paragraph is the run of <code class="display"><span class="extract-syntax">^"This"</span></code> and <code class="display"><span class="extract-syntax">^"That"</span></code> markers at the end of
for a paragraph is the run of <span class="extract"><span class="extract-syntax">^"This"</span></span> and <span class="extract"><span class="extract-syntax">^"That"</span></span> markers at the end of
the line introducing that paragraph. They can only occur, therefore, on a
line beginning with an <code class="display"><span class="extract-syntax">@</span></code>. We extract them into a string called <code class="display"><span class="extract-syntax">tag_list</span></code>.
line beginning with an <span class="extract"><span class="extract-syntax">@</span></span>. We extract them into a string called <span class="extract"><span class="extract-syntax">tag_list</span></span>.
(The reason we can't act on them straight away, which would make for simpler
code, is that they need to be applied to a paragraph structure which doesn't
yet exist &mdash; it will only exist when the line has been fully parsed.)
@ -126,7 +126,7 @@ yet exist &mdash; it will only exist when the line has been fully parsed.)
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1">&#167;1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_2"></a><b>&#167;1.1.2. </b>And now it's later, and we can safely apply the tags. <code class="display"><span class="extract-syntax">current_paragraph</span></code>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1">&#167;1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_2"></a><b>&#167;1.1.2. </b>And now it's later, and we can safely apply the tags. <span class="extract"><span class="extract-syntax">current_paragraph</span></span>
now points to the para which was created by this line, not the one before.
</p>
@ -166,7 +166,7 @@ now points to the para which was created by this line, not the one before.
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">paragraphs</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Work out footnote numbering for this paragraph</span> <span class="named-paragraph-number">1.1.4.3</span>&gt;<span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1">&#167;1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_5"></a><b>&#167;1.1.5. </b>The "purpose" of a section is a brief note about what it's for. In version 1
syntax, this had to be explicitly declared with a <code class="display"><span class="extract-syntax">@Purpose:</span></code> command; in
syntax, this had to be explicitly declared with a <span class="extract"><span class="extract-syntax">@Purpose:</span></span> command; in
version 2 it's much tidier.
</p>
@ -325,7 +325,7 @@ namespace for its functions.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7">&#167;1.1.7</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_3"></a><b>&#167;1.1.7.3. </b>Version 1 syntax was cluttered up with a number of hardly-used markup
syntaxes called "commands", written in double squared brackets <code class="display"><span class="extract-syntax">[[Thus]]</span></code>.
syntaxes called "commands", written in double squared brackets <span class="extract"><span class="extract-syntax">[[Thus]]</span></span>.
In version 2, this notation is never used.
</p>
@ -399,7 +399,7 @@ handling. We'll call these "paragraph macros".
<span class="plain-syntax"> </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7">&#167;1.1.7</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5"></a><b>&#167;1.1.7.5. </b>A structural marker is introduced by an <code class="display"><span class="extract-syntax">@</span></code> in column 1, and is a structural
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7">&#167;1.1.7</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5"></a><b>&#167;1.1.7.5. </b>A structural marker is introduced by an <span class="extract"><span class="extract-syntax">@</span></span> in column 1, and is a structural
division in the current section.
</p>
@ -599,11 +599,11 @@ division in the current section.
<span class="plain-syntax"> </span><span class="identifier-syntax">latest</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next_line</span><span class="plain-syntax"> = </span><span class="identifier-syntax">EEL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">code_lcat_for_body</span><span class="plain-syntax"> = </span><span class="constant-syntax">TEXT_EXTRACT_LCAT</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">extract_mode</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_7">&#167;1.1.7.7</a> (three times).</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1"></a><b>&#167;1.1.7.5.1. </b>So here we have the possibilities which start with a column-1 <code class="display"><span class="extract-syntax">@</span></code> sign.
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_7">&#167;1.1.7.7</a> (three times).</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1"></a><b>&#167;1.1.7.5.1. </b>So here we have the possibilities which start with a column-1 <span class="extract"><span class="extract-syntax">@</span></span> sign.
There appear to be hordes of these, but in fact most of them were removed
in Inweb syntax version 2: in modern syntax, only <code class="display"><span class="extract-syntax">@d</span></code>, <code class="display"><span class="extract-syntax">@e</span></code>, <code class="display"><span class="extract-syntax">@h</span></code>, their
long forms <code class="display"><span class="extract-syntax">@define</span></code>, <code class="display"><span class="extract-syntax">@enum</span></code> and <code class="display"><span class="extract-syntax">@heading</span></code>, and plain old <code class="display"><span class="extract-syntax">@</span></code> remain.
(But <code class="display"><span class="extract-syntax">@e</span></code> has a different meaning from in version 1.)
in Inweb syntax version 2: in modern syntax, only <span class="extract"><span class="extract-syntax">@d</span></span>, <span class="extract"><span class="extract-syntax">@e</span></span>, <span class="extract"><span class="extract-syntax">@h</span></span>, their
long forms <span class="extract"><span class="extract-syntax">@define</span></span>, <span class="extract"><span class="extract-syntax">@enum</span></span> and <span class="extract"><span class="extract-syntax">@heading</span></span>, and plain old <span class="extract"><span class="extract-syntax">@</span></span> remain.
(But <span class="extract"><span class="extract-syntax">@e</span></span> has a different meaning from in version 1.)
</p>
@ -703,7 +703,7 @@ in the file made of hyphens, called "the bar". All of that has gone in V2.
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">is_commentary</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">before_bar</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">next_par_number</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_4"></a><b>&#167;1.1.7.5.1.4. </b>An <code class="display"><span class="extract-syntax">@</span></code> sign in the first column, followed by a row of four or more dashes,
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_4"></a><b>&#167;1.1.7.5.1.4. </b>An <span class="extract"><span class="extract-syntax">@</span></span> sign in the first column, followed by a row of four or more dashes,
constitutes the optional division bar in a section.
</p>
@ -725,7 +725,7 @@ constitutes the optional division bar in a section.
<span class="plain-syntax"> </span><span class="identifier-syntax">next_par_number</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_5"></a><b>&#167;1.1.7.5.1.5. </b>In version 1, the division point where a paragraoh begins to go into
verbatim code was not marked with an equals sign, but with one of the three
commands <code class="display"><span class="extract-syntax">@c</span></code> ("code"), <code class="display"><span class="extract-syntax">@e</span></code> ("early code") and <code class="display"><span class="extract-syntax">@x</span></code> ("code-like extract").
commands <span class="extract"><span class="extract-syntax">@c</span></span> ("code"), <span class="extract"><span class="extract-syntax">@e</span></span> ("early code") and <span class="extract"><span class="extract-syntax">@x</span></span> ("code-like extract").
These had identical behaviour except for whether or not to tangle what
follows:
</p>
@ -747,8 +747,8 @@ follows:
<span class="plain-syntax"> </span><span class="identifier-syntax">comment_mode</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">code_plainness_for_body</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">hyperlink_body</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_6"></a><b>&#167;1.1.7.5.1.6. </b>This is for <code class="display"><span class="extract-syntax">@d</span></code> and <code class="display"><span class="extract-syntax">@define</span></code>. Definitions are intended to translate to
C preprocessor macros, Inform 6 <code class="display"><span class="extract-syntax">Constant</span></code>s, and so on.
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_6"></a><b>&#167;1.1.7.5.1.6. </b>This is for <span class="extract"><span class="extract-syntax">@d</span></span> and <span class="extract"><span class="extract-syntax">@define</span></span>. Definitions are intended to translate to
C preprocessor macros, Inform 6 <span class="extract"><span class="extract-syntax">Constant</span></span>s, and so on.
</p>
@ -772,8 +772,8 @@ C preprocessor macros, Inform 6 <code class="display"><span class="extract-synta
<span class="plain-syntax"> </span><span class="identifier-syntax">comment_mode</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">is_commentary</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a> (three times).</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_7"></a><b>&#167;1.1.7.5.1.7. </b>This is for <code class="display"><span class="extract-syntax">@e</span></code> (in version 2) and <code class="display"><span class="extract-syntax">@enum</span></code>, which makes an automatically
enumerated sort of <code class="display"><span class="extract-syntax">@d</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a> (three times).</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_7"></a><b>&#167;1.1.7.5.1.7. </b>This is for <span class="extract"><span class="extract-syntax">@e</span></span> (in version 2) and <span class="extract"><span class="extract-syntax">@enum</span></span>, which makes an automatically
enumerated sort of <span class="extract"><span class="extract-syntax">@d</span></span>.
</p>
@ -809,11 +809,11 @@ enumerated sort of <code class="display"><span class="extract-syntax">@d</span><
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">is_commentary</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7_5_1">&#167;1.1.7.5.1</a> (twice).</li></ul><p class="inwebparagraph"><a id="SP1_1_7_5_1_8"></a><b>&#167;1.1.7.5.1.8. </b>Here we handle paragraph breaks which may or may not be headings. In
version 1, <code class="display"><span class="extract-syntax">@p</span></code> was a heading, and <code class="display"><span class="extract-syntax">@pp</span></code> a grander heading, while plain <code class="display"><span class="extract-syntax">@</span></code>
version 1, <span class="extract"><span class="extract-syntax">@p</span></span> was a heading, and <span class="extract"><span class="extract-syntax">@pp</span></span> a grander heading, while plain <span class="extract"><span class="extract-syntax">@</span></span>
is no heading at all. The use of "p" was a little confusing, and went back
to CWEB, which used the term "paragraph" differently from us: it was "p"
short for what CWEB called a "paragraph". We now use <code class="display"><span class="extract-syntax">@h</span></code> or equivalently
<code class="display"><span class="extract-syntax">@heading</span></code> for a heading.
short for what CWEB called a "paragraph". We now use <span class="extract"><span class="extract-syntax">@h</span></span> or equivalently
<span class="extract"><span class="extract-syntax">@heading</span></span> for a heading.
</p>
<p class="inwebparagraph">The noteworthy thing here is the way we fool around with the text on the line
@ -881,14 +881,14 @@ of French weaving" and the remainder,
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">next_child_number</span><span class="plain-syntax">; </span><span class="comment"> used when working out paragraph numbers</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">parent_paragraph</span><span class="plain-syntax">; </span><span class="comment"> ditto</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">weight</span><span class="plain-syntax">; </span><span class="comment"> typographic prominence: one of the </span><code class="display"><span class="extract-syntax">*_WEIGHT</span></code><span class="comment"> values</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">weight</span><span class="plain-syntax">; </span><span class="comment"> typographic prominence: one of the </span><span class="extract"><span class="extract-syntax">*_WEIGHT</span></span><span class="comment"> values</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">starts_on_new_page</span><span class="plain-syntax">; </span><span class="comment"> relevant for weaving to TeX only, of course</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">para_macro</span><span class="plain-syntax"> *</span><span class="identifier-syntax">defines_macro</span><span class="plain-syntax">; </span><span class="comment"> there can only be one</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">functions</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">function</span></code><span class="comment">: those defined in this para</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">structures</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">language_type</span></code><span class="comment">: similarly</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">taggings</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">paragraph_tagging</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">footnotes</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">footnote</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">functions</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">function</span></span><span class="comment">: those defined in this para</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">structures</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">language_type</span></span><span class="comment">: similarly</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">taggings</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">paragraph_tagging</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">footnotes</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">footnote</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">first_line_in_paragraph</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">section</span><span class="plain-syntax"> *</span><span class="identifier-syntax">under_section</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
@ -945,7 +945,7 @@ of French weaving" and the remainder,
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">text_operand</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7">&#167;1.1.7</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_9"></a><b>&#167;1.1.7.9. </b>Note that in an <code class="display"><span class="extract-syntax">@d</span></code> definition, a blank line is treated as the end of the
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7">&#167;1.1.7</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_7_9"></a><b>&#167;1.1.7.9. </b>Note that in an <span class="extract"><span class="extract-syntax">@d</span></span> definition, a blank line is treated as the end of the
definition. (This is unnecessary for C, and is a point of difference with
CWEB, but is needed for languages which don't allow multi-line definitions.)
</p>
@ -972,7 +972,7 @@ CWEB, but is needed for languages which don't allow multi-line definitions.)
<span class="plain-syntax"> </span><a href="4-lm.html#SP5" class="function-link"><span class="function-syntax">LanguageMethods::subcategorise_line</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_language</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="2-tp.html#SP1_1_7">&#167;1.1.7</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_4_1"></a><b>&#167;1.1.4.1. </b>The purpose text occurs just below the heading. In version 1 it's cued with
a <code class="display"><span class="extract-syntax">@Purpose:</span></code> command; in version 2 it is unmarked. The following routine
a <span class="extract"><span class="extract-syntax">@Purpose:</span></span> command; in version 2 it is unmarked. The following routine
is not elegant but handles the back end of both possibilities.
</p>
@ -995,8 +995,8 @@ is not elegant but handles the back end of both possibilities.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">footnote</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">footnote_cue_number</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">FOOTNOTE_TEXT_LCAT</span></code><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">footnote_text_number</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">FOOTNOTE_TEXT_LCAT</span></code><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">footnote_cue_number</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">FOOTNOTE_TEXT_LCAT</span></span><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">footnote_text_number</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">FOOTNOTE_TEXT_LCAT</span></span><span class="comment"> lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cue_text</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">cued_already</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>

50
docs/inweb/2-tr.html
View file

@ -59,13 +59,13 @@ stand-alone files called "tangle targets". By default there is just one
of these.
</p>
<p class="inwebparagraph">We use the <code class="display"><span class="extract-syntax">WebMetadata::get</span></code> function of <code class="display"><span class="extract-syntax">foundation</span></code> to read the structure
of the web in from the file system. This produces a <code class="display"><span class="extract-syntax">web_md</span></code> metadata
structure for the web itself, which contains a list of <code class="display"><span class="extract-syntax">chapter_md</span></code>
structures for the chapters, each in turn containing a list of <code class="display"><span class="extract-syntax">section_md</span></code>s.
<p class="inwebparagraph">We use the <span class="extract"><span class="extract-syntax">WebMetadata::get</span></span> function of <span class="extract"><span class="extract-syntax">foundation</span></span> to read the structure
of the web in from the file system. This produces a <span class="extract"><span class="extract-syntax">web_md</span></span> metadata
structure for the web itself, which contains a list of <span class="extract"><span class="extract-syntax">chapter_md</span></span>
structures for the chapters, each in turn containing a list of <span class="extract"><span class="extract-syntax">section_md</span></span>s.
We will imitate that structure exactly, but because we want to attach a lot
of semantics at each level, we will make a <code class="display"><span class="extract-syntax">web</span></code> with a list of <code class="display"><span class="extract-syntax">chapter</span></code>s
each of which has a list of <code class="display"><span class="extract-syntax">section</span></code>s.
of semantics at each level, we will make a <span class="extract"><span class="extract-syntax">web</span></span> with a list of <span class="extract"><span class="extract-syntax">chapter</span></span>s
each of which has a list of <span class="extract"><span class="extract-syntax">section</span></span>s.
</p>
<p class="inwebparagraph">Here are the semantics for a web:
@ -74,33 +74,33 @@ each of which has a list of <code class="display"><span class="extract-syntax">s
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">web</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">web_md</span><span class="plain-syntax"> *</span><span class="identifier-syntax">md</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapters</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">chapter</span></code><span class="comment"> (including Sections, Preliminaries, etc.)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">chapters</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">chapter</span></span><span class="comment"> (including Sections, Preliminaries, etc.)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">web_extent</span><span class="plain-syntax">; </span><span class="comment"> total lines in literate source, excluding contents</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">no_paragraphs</span><span class="plain-syntax">; </span><span class="comment"> this will be at least 1</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">main_language</span><span class="plain-syntax">; </span><span class="comment"> in which most of the sections are written</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tangle_targets</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">tangle_target</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tangle_targets</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">tangle_target</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">headers</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">filename</span></code><span class="comment">: additional header files</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">headers</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">filename</span></span><span class="comment">: additional header files</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">analysed</span><span class="plain-syntax">; </span><span class="comment"> has this been scanned for function usage and such?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">language_types</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">language_type</span></code><span class="comment">: used only for C-like languages</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">language_types</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">language_type</span></span><span class="comment">: used only for C-like languages</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">ebook</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_ebook</span><span class="plain-syntax">; </span><span class="comment"> when being woven to an ebook</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">redirect_weaves_to</span><span class="plain-syntax">; </span><span class="comment"> ditto</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">web</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure web is accessed in 1/pc, 1/ts, 1/ptt, 2/lc, 2/tp, 2/pn, 3/ta, 3/ti, 3/tw, 3/twot, 3/tt, 4/pl, 4/taf, 4/as, 4/cl, 4/is, 5/ptf, 5/tf, 5/hf, 5/df, 6/mkf, 6/rw, 6/cln and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>And for a chapter:
</pre><ul class="endnotetexts"><li>The structure web is accessed in 1/pc, 1/ts, 1/ptt, 2/lc, 2/tp, 2/pn, 3/ta, 3/ti, 3/tw, 3/twot, 3/tt, 4/pl, 4/taf, 4/as, 4/cl, 4/is, 5/ptf, 5/tf, 5/hf, 5/df, 5/wp, 6/mkf, 6/rw, 6/cln and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>And for a chapter:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">chapter</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">chapter_md</span><span class="plain-syntax"> *</span><span class="identifier-syntax">md</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owning_web</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">section</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sections</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">section</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_weave</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> unless this chapter produces a weave of its own</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_weave</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> unless this chapter produces a weave of its own</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">titling_line_inserted</span><span class="plain-syntax">; </span><span class="comment"> has an interleaved chapter heading been added yet?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ch_language</span><span class="plain-syntax">; </span><span class="comment"> in which this chapter is written</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
@ -118,26 +118,26 @@ each of which has a list of <code class="display"><span class="extract-syntax">s
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sect_purpose</span><span class="plain-syntax">; </span><span class="comment"> e.g., "To manage the zoo, and feed all penguins"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">barred</span><span class="plain-syntax">; </span><span class="comment"> if version 1 syntax, contains a dividing bar?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sect_language</span><span class="plain-syntax">; </span><span class="comment"> in which this section is written</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">tangle_target</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sect_target</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> unless this section produces a tangle of its own</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sect_weave</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> unless this section produces a weave of its own</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">tangle_target</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sect_target</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> unless this section produces a tangle of its own</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sect_weave</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> unless this section produces a weave of its own</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sect_extent</span><span class="plain-syntax">; </span><span class="comment"> total number of lines in this section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">first_line</span><span class="plain-syntax">; </span><span class="comment"> for efficiency's sake not held as a </span><code class="display"><span class="extract-syntax">linked_list</span></code><span class="comment">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">first_line</span><span class="plain-syntax">; </span><span class="comment"> for efficiency's sake not held as a </span><span class="extract"><span class="extract-syntax">linked_list</span></span><span class="comment">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">last_line</span><span class="plain-syntax">; </span><span class="comment"> but that's what it is, all the same</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sect_paragraphs</span><span class="plain-syntax">; </span><span class="comment"> total number of paragraphs in this section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">paragraphs</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">paragraph</span></code><span class="comment">: the content of this section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">paragraphs</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">paragraph</span></span><span class="comment">: the content of this section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">theme_tag</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tag_with</span><span class="plain-syntax">; </span><span class="comment"> automatically tag paras in this section thus</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">macros</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">para_macro</span></code><span class="comment">: those defined in this section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">macros</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">para_macro</span></span><span class="comment">: those defined in this section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">scratch_flag</span><span class="plain-syntax">; </span><span class="comment"> temporary workspace</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">paused_until_at</span><span class="plain-syntax">; </span><span class="comment"> ignore the top half of the file, until the first </span><code class="display"><span class="extract-syntax">@</span></code><span class="comment"> sign</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">paused_until_at</span><span class="plain-syntax">; </span><span class="comment"> ignore the top half of the file, until the first </span><span class="extract"><span class="extract-syntax">@</span></span><span class="comment"> sign</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">printed_number</span><span class="plain-syntax">; </span><span class="comment"> temporary again: sometimes used in weaving</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">section</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure section is accessed in 1/pc, 1/ts, 1/ptt, 2/lc, 2/tp, 2/pm, 2/tgs, 2/pn, 3/ta, 3/ti, 3/tw, 3/twot, 3/tt, 4/pl, 4/taf, 4/lm, 4/as, 4/is, 5/ptf, 5/tf, 5/hf, 5/df, 6/mkf, 6/rw, 6/cln and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The following routine makes the <code class="display"><span class="extract-syntax">web</span></code>-<code class="display"><span class="extract-syntax">chapter</span></code>-<code class="display"><span class="extract-syntax">section</span></code> tree out of a
<code class="display"><span class="extract-syntax">web_md</span></code>-<code class="display"><span class="extract-syntax">chapter_md</span></code>-<code class="display"><span class="extract-syntax">section_md</span></code> tree:
</pre><ul class="endnotetexts"><li>The structure section is accessed in 1/pc, 1/ts, 1/ptt, 2/lc, 2/tp, 2/pm, 2/tgs, 2/pn, 3/ta, 3/ti, 3/tw, 3/twot, 3/tt, 4/pl, 4/taf, 4/lm, 4/as, 4/is, 5/ptf, 5/tf, 5/hf, 5/df, 6/mkf, 6/rw, 6/cln and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The following routine makes the <span class="extract"><span class="extract-syntax">web</span></span>-<span class="extract"><span class="extract-syntax">chapter</span></span>-<span class="extract"><span class="extract-syntax">section</span></span> tree out of a
<span class="extract"><span class="extract-syntax">web_md</span></span>-<span class="extract"><span class="extract-syntax">chapter_md</span></span>-<span class="extract"><span class="extract-syntax">section_md</span></span> tree:
</p>
<pre class="displayed-code all-displayed-code">
@ -364,7 +364,7 @@ tangled for.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">Reader::woven_folder</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>Reader::woven_folder</b>:<br>The Swarm - <a href="1-ts.html#SP2_2">&#167;2.2</a>, <a href="1-ts.html#SP4">&#167;4</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP8">&#167;8</a>&lt;br&gt;HTML Formats - <a href="5-hf.html#SP15">&#167;15</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">Reader::woven_folder</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>Reader::woven_folder</b>:<br>The Swarm - <a href="1-ts.html#SP2_2">&#167;2.2</a>, <a href="1-ts.html#SP4">&#167;4</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP7">&#167;7</a>&lt;br&gt;HTML Formats - <a href="5-hf.html#SP15">&#167;15</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-pth.html#SP4" class="function-link"><span class="function-syntax">Pathnames::down</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">path_to_web</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Woven"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/3-pth.html#SP9" class="function-link"><span class="function-syntax">Pathnames::create_in_file_system</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_path</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unable to create Woven subdirectory"</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
@ -423,8 +423,8 @@ in large webs, and lookup is performed only a few times.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. Ranges and containment. </b>This provides a sort of partial ordering on ranges, testing if the portion
of the web represented by <code class="display"><span class="extract-syntax">range1</span></code> is contained inside the portion represented
by <code class="display"><span class="extract-syntax">range2</span></code>. Note that <code class="display"><span class="extract-syntax">"0"</span></code> means the entire web, and is what the word <code class="display"><span class="extract-syntax">all</span></code>
of the web represented by <span class="extract"><span class="extract-syntax">range1</span></span> is contained inside the portion represented
by <span class="extract"><span class="extract-syntax">range2</span></span>. Note that <span class="extract"><span class="extract-syntax">"0"</span></span> means the entire web, and is what the word <span class="extract"><span class="extract-syntax">all</span></span>
translates to when it's used on the command line.
</p>
@ -466,7 +466,7 @@ a web contains just one target, which contains all of the sections.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">tt</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. </b>And the following provides a way to iterate through the lines in a tangle,
while keeping the variables <code class="display"><span class="extract-syntax">C</span></code>, <code class="display"><span class="extract-syntax">S</span></code> and <code class="display"><span class="extract-syntax">L</span></code> pointing to the current chapter,
while keeping the variables <span class="extract"><span class="extract-syntax">C</span></span>, <span class="extract"><span class="extract-syntax">S</span></span> and <span class="extract"><span class="extract-syntax">L</span></span> pointing to the current chapter,
section and line.
</p>

32
docs/inweb/3-ta.html
View file

@ -141,8 +141,8 @@ these identifiers.
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">ELEMENT_ACCESS_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000001</span><span class="plain-syntax"> </span><span class="comment"> C-like languages: access via </span><code class="display"><span class="extract-syntax">-&gt;</span></code><span class="comment"> or </span><code class="display"><span class="extract-syntax">.</span></code><span class="comment"> operators to structure element</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">FCALL_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000002</span><span class="plain-syntax"> </span><span class="comment"> C-like languages: function call made using brackets, </span><code class="display"><span class="extract-syntax">name(args)</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">ELEMENT_ACCESS_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000001</span><span class="plain-syntax"> </span><span class="comment"> C-like languages: access via </span><span class="extract"><span class="extract-syntax">-&gt;</span></span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">.</span></span><span class="comment"> operators to structure element</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">FCALL_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000002</span><span class="plain-syntax"> </span><span class="comment"> C-like languages: function call made using brackets, </span><span class="extract"><span class="extract-syntax">name(args)</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PREFORM_IN_CODE_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000004</span><span class="plain-syntax"> </span><span class="comment"> InC only: use of a Preform nonterminal as a C "constant"</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PREFORM_IN_GRAMMAR_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000008</span><span class="plain-syntax"> </span><span class="comment"> InC only: ditto, but within Preform production rather than C code</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">MISC_USAGE</span><span class="plain-syntax"> </span><span class="constant-syntax">0x00000010</span><span class="plain-syntax"> </span><span class="comment"> any other appearance as an identifier</span>
@ -150,7 +150,7 @@ these identifiers.
</pre>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The main analysis routine goes through a web as follows. Note that we only
perform the search here, we don't comment on the results; any action to be
taken must be handled by <code class="display"><span class="extract-syntax">LanguageMethods::late_preweave_analysis</span></code> when we're done.
taken must be handled by <span class="extract"><span class="extract-syntax">LanguageMethods::late_preweave_analysis</span></span> when we're done.
</p>
<pre class="displayed-code all-displayed-code">
@ -184,7 +184,7 @@ below) to look for names of particular functions it knows about.
<p class="inwebparagraph">In Version 1 webs, this code is also expected to parse any Interface lines in
a section which it recognises, marking those by setting their
<code class="display"><span class="extract-syntax">interface_line_identified</span></code> flags. Any that are left must be erroneous.
<span class="extract"><span class="extract-syntax">interface_line_identified</span></span> flags. Any that are left must be erroneous.
Version 2 removed Interface altogeter as being cumbersome for no real gain in
practice.
</p>
@ -221,7 +221,7 @@ practice.
<span class="plain-syntax"> </span><a href="3-ta.html#SP5" class="function-link"><span class="function-syntax">Analyser::analyse_as_code</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text</span><span class="plain-syntax">, </span><span class="constant-syntax">ANY_USAGE</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ta.html#SP4">&#167;4</a>.</li></ul><p class="inwebparagraph"><a id="SP4_4"></a><b>&#167;4.4. </b>Lines in a Preform grammar generally take the form of some BNF grammar, where
we want only to identify any nonterminals mentioned, then a <code class="display"><span class="extract-syntax">==&gt;</span></code> divider,
we want only to identify any nonterminals mentioned, then a <span class="extract"><span class="extract-syntax">==&gt;</span></span> divider,
and then some C code to deal with a match. The code is subjected to analysis
just as any other code would be.
</p>
@ -234,17 +234,17 @@ just as any other code would be.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="3-ta.html#SP5" class="function-link"><span class="function-syntax">Analyser::analyse_as_code</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text_operand2</span><span class="plain-syntax">, </span><span class="constant-syntax">ANY_USAGE</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ta.html#SP5" class="function-link"><span class="function-syntax">Analyser::analyse_as_code</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text_operand</span><span class="plain-syntax">, </span><span class="constant-syntax">PREFORM_IN_CODE_USAGE</span><span class="plain-syntax">, </span><span class="constant-syntax">PREFORM_IN_GRAMMAR_USAGE</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ta.html#SP4">&#167;4</a>.</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Identifier searching. </b>Here's what we actually do, then. We take the code fragment <code class="display"><span class="extract-syntax">text</span></code>, drawn
from part or all of source line <code class="display"><span class="extract-syntax">L</span></code> from web <code class="display"><span class="extract-syntax">W</span></code>, and look for any identifier
names used in one of the contexts in the bitmap <code class="display"><span class="extract-syntax">mask</span></code>. Any that we find are
passed to <code class="display"><span class="extract-syntax">Analyser::analyse_find</span></code>, along with the context they were found in (or, if
<code class="display"><span class="extract-syntax">transf</span></code> is nonzero, with <code class="display"><span class="extract-syntax">transf</span></code> as their context).
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ta.html#SP4">&#167;4</a>.</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Identifier searching. </b>Here's what we actually do, then. We take the code fragment <span class="extract"><span class="extract-syntax">text</span></span>, drawn
from part or all of source line <span class="extract"><span class="extract-syntax">L</span></span> from web <span class="extract"><span class="extract-syntax">W</span></span>, and look for any identifier
names used in one of the contexts in the bitmap <span class="extract"><span class="extract-syntax">mask</span></span>. Any that we find are
passed to <span class="extract"><span class="extract-syntax">Analyser::analyse_find</span></span>, along with the context they were found in (or, if
<span class="extract"><span class="extract-syntax">transf</span></span> is nonzero, with <span class="extract"><span class="extract-syntax">transf</span></span> as their context).
</p>
<p class="inwebparagraph">What we do is to look for instances of an identifier, defined as a maximal
string of <code class="display"><span class="extract-syntax">%i</span></code> characters or hyphens not followed by <code class="display"><span class="extract-syntax">&gt;</span></code> characters. (Thus
<code class="display"><span class="extract-syntax">fish-or-chips</span></code> counts, but <code class="display"><span class="extract-syntax">fish-</span></code> is not an identifier when it occurs in
<code class="display"><span class="extract-syntax">fish-&gt;bone</span></code>.)
string of <span class="extract"><span class="extract-syntax">%i</span></span> characters or hyphens not followed by <span class="extract"><span class="extract-syntax">&gt;</span></span> characters. (Thus
<span class="extract"><span class="extract-syntax">fish-or-chips</span></span> counts, but <span class="extract"><span class="extract-syntax">fish-</span></span> is not an identifier when it occurs in
<span class="extract"><span class="extract-syntax">fish-&gt;bone</span></span>.)
</p>
<pre class="displayed-code all-displayed-code">
@ -315,7 +315,7 @@ in Aho, Sethi and Ullman, "Compilers: Principles, Techniques and Tools"
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hash_table</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">analysis_hash</span><span class="plain-syntax">[</span><span class="constant-syntax">HASH_TAB_SIZE</span><span class="plain-syntax">]; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">hash_table_entry</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">analysis_hash</span><span class="plain-syntax">[</span><span class="constant-syntax">HASH_TAB_SIZE</span><span class="plain-syntax">]; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">hash_table_entry</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">analysis_hash_initialised</span><span class="plain-syntax">; </span><span class="comment"> when we start up, array's contents are undefined</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">hash_table</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure hash_table is accessed in 2/tr, 4/pl and here.</li></ul><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>Where we define:
@ -325,7 +325,7 @@ in Aho, Sethi and Ullman, "Compilers: Principles, Techniques and Tools"
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hash_table_entry</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hash_key</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="reserved-syntax">reserved_word</span><span class="plain-syntax">; </span><span class="comment"> in the language currently being woven, that is</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">usages</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">hash_table_entry_usage</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">usages</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">hash_table_entry_usage</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">definition_line</span><span class="plain-syntax">; </span><span class="comment"> or null, if it's not a constant, function or type name</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">language_function</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_function</span><span class="plain-syntax">; </span><span class="comment"> for function names only</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
@ -422,7 +422,7 @@ same paragraph of code.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hash_table_entry_usage</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">usage_recorded_at</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">form_of_usage</span><span class="plain-syntax">; </span><span class="comment"> bitmap of the </span><code class="display"><span class="extract-syntax">*_USAGE</span></code><span class="comment"> constants defined above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">form_of_usage</span><span class="plain-syntax">; </span><span class="comment"> bitmap of the </span><span class="extract"><span class="extract-syntax">*_USAGE</span></span><span class="comment"> constants defined above</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">hash_table_entry_usage</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure hash_table_entry_usage is accessed in 3/tw, 4/as, 4/is and here.</li></ul><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>And here's how we create these usages:

138
docs/inweb/3-ti.html
View file

@ -45,16 +45,16 @@ function togglePopup(material_id) {
<!--Weave of 'The Indexer' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#3">Chapter 3: Outputs</a></li><li><b>The Indexer</b></li></ul><p class="purpose">To construct indexes of the material woven, following a template.</p>
<ul class="toc"><li><a href="3-ti.html#SP1">&#167;1. Cover sheets</a></li><li><a href="3-ti.html#SP3">&#167;3. Full index pages</a></li><li><a href="3-ti.html#SP6_1_1">&#167;6.1.1. The repeat stack and loops</a></li><li><a href="3-ti.html#SP6_1_8">&#167;6.1.8. Variable substitutions</a></li><li><a href="3-ti.html#SP8">&#167;8. Transcribing CSS</a></li><li><a href="3-ti.html#SP9">&#167;9. Tracking the file being written to</a></li></ul><hr class="tocbar">
<ul class="toc"><li><a href="3-ti.html#SP1">&#167;1. Cover sheets</a></li><li><a href="3-ti.html#SP3">&#167;3. Full index pages</a></li><li><a href="3-ti.html#SP6_1_1">&#167;6.1.1. The repeat stack and loops</a></li><li><a href="3-ti.html#SP6_1_8">&#167;6.1.8. Variable substitutions</a></li><li><a href="3-ti.html#SP8">&#167;8. Tracking the file being written to</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Cover sheets. </b>The indexer offers two basic services. One, which is much simpler, makes
cover sheets, and has only simple escapes (except that it has the ability
to call the fuller indexing service if need be, using <code class="display"><span class="extract-syntax">[[Template T]]</span></code>
or <code class="display"><span class="extract-syntax">[[Navigation]]</span></code>).
to call the fuller indexing service if need be, using <span class="extract"><span class="extract-syntax">[[Template T]]</span></span>
or <span class="extract"><span class="extract-syntax">[[Navigation]]</span></span>).
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::cover_sheet_maker</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>Indexer::cover_sheet_maker</b>:<br><a href="3-ti.html#SP2_1_1">&#167;2.1.1</a>, The Weaver - <a href="3-tw.html#SP1_1">&#167;1.1</a>, <a href="3-tw.html#SP1_2">&#167;1.2</a>&lt;br&gt;HTML Formats - <a href="5-hf.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">unextended_leafname</span><span class="plain-syntax">,</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::cover_sheet_maker</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>Indexer::cover_sheet_maker</b>:<br>The Weaver - <a href="3-tw.html#SP1_1">&#167;1.1</a>, <a href="3-tw.html#SP1_2">&#167;1.2</a>&lt;br&gt;HTML Formats - <a href="5-hf.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">unextended_leafname</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wt</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">halves</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cover_sheet_state</span><span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Clear the cover sheet state</span> <span class="named-paragraph-number">1.2</span>&gt;<span class="plain-syntax">;</span>
@ -68,7 +68,7 @@ or <code class="display"><span class="extract-syntax">[[Navigation]]</span></cod
<span class="plain-syntax"> </span><a href="3-ti.html#SP2" class="function-link"><span class="function-syntax">Indexer::scan_cover_line</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">state</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP1_1"></a><b>&#167;1.1. </b>The cover-sheet-maker has the ability to weave only the top half, or only
the bottom half, of the template; they are divided by the marker <code class="display"><span class="extract-syntax">[[Code]]</span></code>.
the bottom half, of the template; they are divided by the marker <span class="extract"><span class="extract-syntax">[[Code]]</span></span>.
</p>
@ -109,20 +109,13 @@ structure.
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">include</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> ((</span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">self_contained</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax">)) &amp;&amp;</span>
<span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *%&lt;link href=%\"(%c+?)\"%c*"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CSS_file</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP5" class="function-link"><span class="function-syntax">Patterns::obtain_filename</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::transcribe_CSS</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">CSS_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c*?)%[%[(%c*?)%]%](%c*)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">left</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">command</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">right</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[2];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">left</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Deal with a double-squares escape in a cover sheet</span> <span class="named-paragraph-number">2.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">right</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c*?)%[%[(%c*?)%]%](%c*)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">left</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">command</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">right</span><span class="plain-syntax"> = </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[2];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">left</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Deal with a double-squares escape in a cover sheet</span> <span class="named-paragraph-number">2.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">right</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">);</span>
@ -139,40 +132,23 @@ structure.
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP22" class="function-link"><span class="function-syntax">Str::eq_wide_string</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">command</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Plugins"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="5-wp.html#SP4" class="function-link"><span class="function-syntax">WeavePlugins::begin_inclusions</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP9" class="function-link"><span class="function-syntax">Patterns::include_plugins</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::include_plugins</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ts.html#SP3" class="function-link"><span class="function-syntax">Swarm::include_plugins</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP22" class="function-link"><span class="function-syntax">Str::eq_wide_string</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">command</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Cover Sheet"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">Weave in the parent pattern's cover sheet</span> <span class="named-paragraph-number">2.1.1</span>&gt;<span class="character-syntax">;</span>
<span class="character-syntax"> } else if (Regexp::match(&amp;mr2, command, L"Navigation")) {</span>
<span class="character-syntax"> if (include) </span>&lt;<span class="named-paragraph">Weave in navigation</span> <span class="named-paragraph-number">2.1.2</span>&gt;<span class="character-syntax">;</span>
<span class="character-syntax"> } else if (Regexp::match(&amp;mr2, command, L"Template (%c*?)")) {</span>
<span class="character-syntax"> if (include) </span>&lt;<span class="named-paragraph">Weave in an index</span> <span class="named-paragraph-number">2.1.3</span>&gt;<span class="character-syntax">;</span>
<span class="character-syntax"> } else if (Bibliographic::data_exists(state-&gt;target-&gt;weave_web-&gt;md, command)) {</span>
<span class="character-syntax"> if (include) </span>&lt;<span class="named-paragraph">Weave in the value of this variable name</span> <span class="named-paragraph-number">2.1.4</span>&gt;<span class="character-syntax">;</span>
<span class="character-syntax"> } else {</span>
<span class="character-syntax"> if (include) WRITE("[[%S]]", command);</span>
<span class="character-syntax"> }</span>
<span class="character-syntax"> Regexp::dispose_of(&amp;mr2);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1"></a><b>&#167;2.1.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in the parent pattern's cover sheet</span> <span class="named-paragraph-number">2.1.1</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">saved</span><span class="plain-syntax"> = </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax"> = </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">based_on</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP1" class="function-link"><span class="function-syntax">Indexer::cover_sheet_maker</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"cover-sheet"</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">halves</span><span class="plain-syntax"> &amp; (</span><span class="constant-syntax">WEAVE_FIRST_HALF</span><span class="plain-syntax"> + </span><span class="constant-syntax">WEAVE_SECOND_HALF</span><span class="plain-syntax">)));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax"> = </span><span class="identifier-syntax">saved</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">, </span><span class="identifier-syntax">command</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Navigation"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">Weave in navigation</span> <span class="named-paragraph-number">2.1.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">, </span><span class="identifier-syntax">command</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Template (%c*?)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">Weave in an index</span> <span class="named-paragraph-number">2.1.2</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::data_exists</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">command</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">Weave in the value of this variable name</span> <span class="named-paragraph-number">2.1.3</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"cover sheet recursively includes itself"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">include</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"[[%S]]"</span><span class="plain-syntax">, </span><span class="identifier-syntax">command</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_2"></a><b>&#167;2.1.2. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in navigation</span> <span class="named-paragraph-number">2.1.2</span>&gt; =
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr2</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1"></a><b>&#167;2.1.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in navigation</span> <span class="named-paragraph-number">2.1.1</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
@ -184,8 +160,8 @@ structure.
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PRINT</span><span class="plain-syntax">(</span><span class="string-syntax">"Warning: no sidebar links will be generated, as -navigation is unset"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_3"></a><b>&#167;2.1.3. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in an index</span> <span class="named-paragraph-number">2.1.3</span>&gt; =
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_2"></a><b>&#167;2.1.2. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in an index</span> <span class="named-paragraph-number">2.1.2</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
@ -194,8 +170,8 @@ structure.
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"pattern does not provide this template file"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP3" class="function-link"><span class="function-syntax">Indexer::incorporate_template_for_target</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">target</span><span class="plain-syntax">, </span><span class="identifier-syntax">CF</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_4"></a><b>&#167;2.1.4. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in the value of this variable name</span> <span class="named-paragraph-number">2.1.4</span>&gt; =
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_3"></a><b>&#167;2.1.3. </b><code class="display">
&lt;<span class="named-paragraph-defn">Weave in the value of this variable name</span> <span class="named-paragraph-number">2.1.3</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
@ -217,7 +193,7 @@ being accessed directly.
<span class="plain-syntax"> </span><a href="3-ti.html#SP3" class="function-link"><span class="function-syntax">Indexer::incorporate_template</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">""</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::incorporate_template_for_target</span><button class="popup" onclick="togglePopup('usagePopup4')">...<span class="popuptext" id="usagePopup4">Usage of <b>Indexer::incorporate_template_for_target</b>:<br><a href="3-ti.html#SP2_1_2">&#167;2.1.2</a>, <a href="3-ti.html#SP2_1_3">&#167;2.1.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wv</span><span class="plain-syntax">,</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::incorporate_template_for_target</span><button class="popup" onclick="togglePopup('usagePopup4')">...<span class="popuptext" id="usagePopup4">Usage of <b>Indexer::incorporate_template_for_target</b>:<br><a href="3-ti.html#SP2_1_1">&#167;2.1.1</a>, <a href="3-ti.html#SP2_1_2">&#167;2.1.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wv</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP3" class="function-link"><span class="function-syntax">Indexer::incorporate_template</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_range</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">navigation</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">breadcrumbs</span><span class="plain-syntax">);</span>
@ -299,7 +275,7 @@ being accessed directly.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::run_engine</span><button class="popup" onclick="togglePopup('usagePopup8')">...<span class="popuptext" id="usagePopup8">Usage of <b>Indexer::run_engine</b>:<br><a href="3-ti.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="reserved-syntax">index_engine_state</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ies</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">save_cf</span><span class="plain-syntax"> = </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">save_cf</span><span class="plain-syntax"> = </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">lpos</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment"> This is our program counter: a line number in the template</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">lpos</span><span class="plain-syntax"> &lt; </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">no_tlines</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::create_mr</span></a><span class="plain-syntax">();</span>
@ -313,7 +289,7 @@ being accessed directly.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">inside_navigation_submenu</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;/ul&gt;"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">inside_navigation_submenu</span><span class="plain-syntax"> = </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">save_cf</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">save_cf</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6_1"></a><b>&#167;6.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Make any necessary substitutions to turn tl into final output</span> <span class="named-paragraph-number">6.1</span>&gt; =
@ -323,12 +299,6 @@ being accessed directly.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">tl</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c*?) "</span><span class="plain-syntax">)) </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tl</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]); </span><span class="comment"> Strip trailing spaces</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="constant-syntax">TRACE_CI_EXECUTION</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Print line and contents of repeat stack</span> <span class="named-paragraph-number">6.1.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">nav_pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">tl</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" *%&lt;link href=%\"(%c+?)\"%c*"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CSS_file</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP5" class="function-link"><span class="function-syntax">Patterns::obtain_filename</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">nav_pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::transcribe_CSS</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">CSS_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::clear</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tl</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">tl</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"%[%[(%c+)%]%]"</span><span class="plain-syntax">)) ||</span>
<span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">tl</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">" %[%[(%c+)%]%]"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">command</span><span class="plain-syntax">);</span>
@ -498,8 +468,8 @@ chapter as its value during the sole iteration.
<span class="plain-syntax"> </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">repeat_stack_variable</span><span class="plain-syntax">[</span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">stack_pointer</span><span class="plain-syntax">-1])</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">goto</span><span class="plain-syntax"> </span><span class="identifier-syntax">CYCLE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1">&#167;6.1</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_6"></a><b>&#167;6.1.6. </b>If called with level <code class="display"><span class="extract-syntax">CHAPTER_LEVEL</span></code>, this returns the topmost chapter number
on the stack; and similarly for <code class="display"><span class="extract-syntax">SECTION_LEVEL</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1">&#167;6.1</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_6"></a><b>&#167;6.1.6. </b>If called with level <span class="extract"><span class="extract-syntax">CHAPTER_LEVEL</span></span>, this returns the topmost chapter number
on the stack; and similarly for <span class="extract"><span class="extract-syntax">SECTION_LEVEL</span></span>.
</p>
@ -610,7 +580,7 @@ its square-bracketed parts.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">right_part</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1">&#167;6.1</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_1"></a><b>&#167;6.1.8.1. </b>This is why, for instance, <code class="display"><span class="extract-syntax">[[Author]]</span></code> is replaced by the author's name:
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1">&#167;6.1</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_1"></a><b>&#167;6.1.8.1. </b>This is why, for instance, <span class="extract"><span class="extract-syntax">[[Author]]</span></span> is replaced by the author's name:
</p>
@ -620,7 +590,7 @@ its square-bracketed parts.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::get_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">for_web</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">varname</span><span class="plain-syntax">));</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_2"></a><b>&#167;6.1.8.2. </b><code class="display"><span class="extract-syntax">[[Navigation]]</span></code> substitutes to the content of the sidebar navigation file;
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_2"></a><b>&#167;6.1.8.2. </b><span class="extract"><span class="extract-syntax">[[Navigation]]</span></span> substitutes to the content of the sidebar navigation file;
this will recursively call the Indexer, in fact.
</p>
@ -648,9 +618,9 @@ this will recursively call the Indexer, in fact.
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="6-cln.html#SP6" class="function-link"><span class="function-syntax">Colonies::drop_initial_breadcrumbs</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">(),</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP6" class="function-link"><span class="function-syntax">Colonies::drop_initial_breadcrumbs</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">(),</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">crumbs</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_4"></a><b>&#167;6.1.8.4. </b><code class="display"><span class="extract-syntax">[[Plugins]]</span></code> here expands to material needed by any plugins required
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_4"></a><b>&#167;6.1.8.4. </b><span class="extract"><span class="extract-syntax">[[Plugins]]</span></span> here expands to material needed by any plugins required
by the weave ies-&gt;nav_pattern itself; it doesn't include optional extras for a
specific page because, of course, the Indexer is used for cover sheets and
not pages. (Except for navigation purposes, and navigation files should never
@ -664,7 +634,7 @@ use this.)
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="5-wp.html#SP4" class="function-link"><span class="function-syntax">WeavePlugins::begin_inclusions</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP9" class="function-link"><span class="function-syntax">Patterns::include_plugins</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">for_web</span><span class="plain-syntax">, </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">nav_pattern</span><span class="plain-syntax">, </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::include_plugins</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">for_web</span><span class="plain-syntax">, </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">nav_pattern</span><span class="plain-syntax">, </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_5"></a><b>&#167;6.1.8.5. </b>A list of all modules in the current web.
</p>
@ -784,7 +754,7 @@ navigation purposes.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()),</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()),</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-pth.html#SP5" class="function-link"><span class="function-syntax">Pathnames::from_text</span></a><span class="plain-syntax">(</span><a href="6-cln.html#SP9" class="function-link"><span class="function-syntax">Colonies::home</span></a><span class="plain-syntax">()));</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_10"></a><b>&#167;6.1.8.10. </b><code class="display">
&lt;<span class="named-paragraph-defn">Substitute a URL</span> <span class="named-paragraph-number">6.1.8.10</span>&gt; =
@ -792,7 +762,7 @@ navigation purposes.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()),</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()),</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-pth.html#SP5" class="function-link"><span class="function-syntax">Pathnames::from_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">link_text</span><span class="plain-syntax">));</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_11"></a><b>&#167;6.1.8.11. </b><code class="display">
&lt;<span class="named-paragraph-defn">Substitute a Link</span> <span class="named-paragraph-number">6.1.8.11</span>&gt; =
@ -800,7 +770,7 @@ navigation purposes.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"&lt;a href=\""</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP11" class="function-link"><span class="function-syntax">Colonies::reference_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="identifier-syntax">link_text</span><span class="plain-syntax">, </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP11" class="function-link"><span class="function-syntax">Colonies::reference_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="identifier-syntax">link_text</span><span class="plain-syntax">, </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"\"&gt;"</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_12"></a><b>&#167;6.1.8.12. </b><code class="display">
&lt;<span class="named-paragraph-defn">Substitute a Menu</span> <span class="named-paragraph-number">6.1.8.12</span>&gt; =
@ -830,7 +800,7 @@ navigation purposes.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP11" class="function-link"><span class="function-syntax">Colonies::reference_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="identifier-syntax">link_text</span><span class="plain-syntax">, </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP11" class="function-link"><span class="function-syntax">Colonies::reference_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="identifier-syntax">link_text</span><span class="plain-syntax">, </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Substitute an item at this URL</span> <span class="named-paragraph-number">6.1.8.14.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_15"></a><b>&#167;6.1.8.15. </b><code class="display">
@ -839,7 +809,7 @@ navigation purposes.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP11" class="function-link"><span class="function-syntax">Colonies::link_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="identifier-syntax">link_text</span><span class="plain-syntax">, </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span><a href="6-cln.html#SP11" class="function-link"><span class="function-syntax">Colonies::link_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="identifier-syntax">link_text</span><span class="plain-syntax">, </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Substitute an item at this URL</span> <span class="named-paragraph-number">6.1.8.14.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-ti.html#SP6_1_8">&#167;6.1.8</a>.</li></ul><p class="inwebparagraph"><a id="SP6_1_8_14_1"></a><b>&#167;6.1.8.14.1. </b><code class="display">
@ -850,7 +820,7 @@ navigation purposes.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">inside_navigation_submenu</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"&lt;ul&gt;"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ies</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">inside_navigation_submenu</span><span class="plain-syntax"> = </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"&lt;li&gt;"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><a href="../foundation-module/3-fln.html#SP7" class="function-link"><span class="function-syntax">Filenames::get_leafname</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()))) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><a href="../foundation-module/3-fln.html#SP7" class="function-link"><span class="function-syntax">Filenames::get_leafname</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()))) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"&lt;span class=\"unlink\"&gt;"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Substitute icon and name</span> <span class="named-paragraph-number">6.1.8.14.1.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"&lt;/span&gt;"</span><span class="plain-syntax">);</span>
@ -876,7 +846,7 @@ navigation purposes.
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax"> = </span><a href="6-cln.html#SP9" class="function-link"><span class="function-syntax">Colonies::assets_path</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">I</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">I</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-pth.html#SP5" class="function-link"><span class="function-syntax">Pathnames::from_text</span></a><span class="plain-syntax">(</span><a href="6-cln.html#SP9" class="function-link"><span class="function-syntax">Colonies::home</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()), </span><span class="identifier-syntax">I</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::current_file</span></a><span class="plain-syntax">()), </span><span class="identifier-syntax">I</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"%S\" height=18&gt; "</span><span class="plain-syntax">, </span><span class="identifier-syntax">icon_text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">substituted</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">item_name</span><span class="plain-syntax">);</span>
@ -896,28 +866,14 @@ navigation purposes.
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">module</span><span class="plain-syntax">, </span><span class="identifier-syntax">M</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">dependencies</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP7" class="function-link"><span class="function-syntax">Indexer::list_module</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Transcribing CSS. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::transcribe_CSS</span><button class="popup" onclick="togglePopup('usagePopup13')">...<span class="popuptext" id="usagePopup13">Usage of <b>Indexer::transcribe_CSS</b>:<br><a href="3-ti.html#SP2">&#167;2</a>, <a href="3-ti.html#SP6_1">&#167;6.1</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CSS_file</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;style type=\"text/css\"&gt;\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-tf.html#SP5" class="function-link"><span class="function-syntax">TextFiles::read</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CSS_file</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">, </span><span class="string-syntax">"can't open CSS file"</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">, </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::copy_CSS</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n&lt;/style&gt;\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::copy_CSS</span><button class="popup" onclick="togglePopup('usagePopup14')">...<span class="popuptext" id="usagePopup14">Usage of <b>Indexer::copy_CSS</b>:<br>none</span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">X</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">X</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Tracking the file being written to. </b></p>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Tracking the file being written to. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">file_being_woven</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Indexer::current_file</span><button class="popup" onclick="togglePopup('usagePopup15')">...<span class="popuptext" id="usagePopup15">Usage of <b>Indexer::current_file</b>:<br><a href="3-ti.html#SP6">&#167;6</a>, <a href="3-ti.html#SP6_1_8_3">&#167;6.1.8.3</a>, <a href="3-ti.html#SP6_1_8_4">&#167;6.1.8.4</a>, <a href="3-ti.html#SP6_1_8_9">&#167;6.1.8.9</a>, <a href="3-ti.html#SP6_1_8_10">&#167;6.1.8.10</a>, <a href="3-ti.html#SP6_1_8_11">&#167;6.1.8.11</a>, <a href="3-ti.html#SP6_1_8_14">&#167;6.1.8.14</a>, <a href="3-ti.html#SP6_1_8_15">&#167;6.1.8.15</a>, <a href="3-ti.html#SP6_1_8_14_1">&#167;6.1.8.14.1</a>, <a href="3-ti.html#SP6_1_8_14_1_1">&#167;6.1.8.14.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="function-syntax">Indexer::current_file</span><button class="popup" onclick="togglePopup('usagePopup13')">...<span class="popuptext" id="usagePopup13">Usage of <b>Indexer::current_file</b>:<br><a href="3-ti.html#SP6">&#167;6</a>, <a href="3-ti.html#SP6_1_8_3">&#167;6.1.8.3</a>, <a href="3-ti.html#SP6_1_8_4">&#167;6.1.8.4</a>, <a href="3-ti.html#SP6_1_8_9">&#167;6.1.8.9</a>, <a href="3-ti.html#SP6_1_8_10">&#167;6.1.8.10</a>, <a href="3-ti.html#SP6_1_8_11">&#167;6.1.8.11</a>, <a href="3-ti.html#SP6_1_8_14">&#167;6.1.8.14</a>, <a href="3-ti.html#SP6_1_8_15">&#167;6.1.8.15</a>, <a href="3-ti.html#SP6_1_8_14_1">&#167;6.1.8.14.1</a>, <a href="3-ti.html#SP6_1_8_14_1_1">&#167;6.1.8.14.1.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">file_being_woven</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::set_current_file</span><button class="popup" onclick="togglePopup('usagePopup16')">...<span class="popuptext" id="usagePopup16">Usage of <b>Indexer::set_current_file</b>:<br><a href="3-ti.html#SP6">&#167;6</a>, The Swarm - <a href="1-ts.html#SP4">&#167;4</a>&lt;br&gt;The Weaver - <a href="3-tw.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Indexer::set_current_file</span><button class="popup" onclick="togglePopup('usagePopup14')">...<span class="popuptext" id="usagePopup14">Usage of <b>Indexer::set_current_file</b>:<br><a href="3-ti.html#SP6">&#167;6</a>, The Swarm - <a href="1-ts.html#SP4">&#167;4</a>&lt;br&gt;The Weaver - <a href="3-tw.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">file_being_woven</span><span class="plain-syntax"> = </span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><hr class="tocbar">

20
docs/inweb/3-tt.html
View file

@ -47,7 +47,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="3-tt.html#SP1">&#167;1. The Master Tangler</a></li><li><a href="3-tt.html#SP3">&#167;3. The Code Tangler</a></li><li><a href="3-tt.html#SP4">&#167;4. Prinary target</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. The Master Tangler. </b>Here's what has happened so far, on a <code class="display"><span class="extract-syntax">-tangle</span></code> run of Inweb: on any
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. The Master Tangler. </b>Here's what has happened so far, on a <span class="extract"><span class="extract-syntax">-tangle</span></span> run of Inweb: on any
other sort of run, of course, we would never be in this section of code.
The web was read completely into memory, and then fully parsed, with all
of the arrays and hashes populated. Program Control then sent us straight
@ -96,7 +96,7 @@ of which can be seen below.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">placed_very_early</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">defines_macro</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><a href="3-tt.html#SP2" class="function-link"><span class="function-syntax">Tangler::tangle_paragraph</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="comment"> (b) Results of </span><code class="display"><span class="extract-syntax">@d</span></code><span class="comment"> declarations</span>
<span class="plain-syntax"> </span><span class="comment"> (b) Results of </span><span class="extract"><span class="extract-syntax">@d</span></span><span class="comment"> declarations</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Tangle all the constant definitions in section order</span> <span class="named-paragraph-number">1.1.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="comment"> (c) Miscellaneous automated C predeclarations</span>
@ -114,7 +114,7 @@ of which can be seen below.
<span class="plain-syntax"> </span><span class="comment"> (f) Opposite of the shebang: a footer</span>
<span class="plain-syntax"> </span><a href="4-lm.html#SP20" class="function-link"><span class="function-syntax">LanguageMethods::gnabehs</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">lang</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tt.html#SP1">&#167;1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_1"></a><b>&#167;1.1.1. </b>This is the result of all those <code class="display"><span class="extract-syntax">@d</span></code> definitions; note that these sometimes
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tt.html#SP1">&#167;1</a>.</li></ul><p class="inwebparagraph"><a id="SP1_1_1"></a><b>&#167;1.1.1. </b>This is the result of all those <span class="extract"><span class="extract-syntax">@d</span></span> definitions; note that these sometimes
extend across multiple lines.
</p>
@ -163,7 +163,7 @@ extend across multiple lines.
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">headers</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-shl.html#SP3" class="function-link"><span class="function-syntax">Shell::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><a href="2-tr.html#SP7" class="function-link"><span class="function-syntax">Reader::tangled_folder</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">), </span><span class="string-syntax">""</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tt.html#SP1">&#167;1</a>.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>So here is the main tangler for a single paragraph. We basically expect to
act only on <code class="display"><span class="extract-syntax">CODE_BODY_LCAT</span></code> lines (those containing actual code), unless
act only on <span class="extract"><span class="extract-syntax">CODE_BODY_LCAT</span></span> lines (those containing actual code), unless
something quirky has been done to support a language feature.
</p>
@ -203,7 +203,7 @@ else; if so, here's where we use it.
<span class="plain-syntax"> </span><a href="4-lm.html#SP15" class="function-link"><span class="function-syntax">LanguageMethods::insert_line_marker</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">under_section</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_language</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tt.html#SP2">&#167;2</a> (twice).</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. The Code Tangler. </b>All of the final tangled code passes through the following routine.
Almost all of the time, it simply prints <code class="display"><span class="extract-syntax">original</span></code> verbatim to the file <code class="display"><span class="extract-syntax">OUT</span></code>.
Almost all of the time, it simply prints <span class="extract"><span class="extract-syntax">original</span></span> verbatim to the file <span class="extract"><span class="extract-syntax">OUT</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -226,17 +226,17 @@ example, we handle
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> if (banana_count == 0) @&lt;Yes, we have no bananas@&gt;;</span>
</pre>
<p class="inwebparagraph">by calling the lower-level tangler on <code class="display"><span class="extract-syntax">if (banana_count == 0) </span></code> (a substring
<p class="inwebparagraph">by calling the lower-level tangler on <span class="extract"><span class="extract-syntax">if (banana_count == 0) </span></span> (a substring
which we know can't involve any macros, since we are detecting macros from
left to right, and this is to the left of the one we found); then by tangling
the definition of "Yes, we have no bananas"; then by calling the upper-level
code tangler on <code class="display"><span class="extract-syntax">;</span></code>. (In this case, of course, there's nothing much there,
code tangler on <span class="extract"><span class="extract-syntax">;</span></span>. (In this case, of course, there's nothing much there,
but in principle it could contain further macros.)
</p>
<p class="inwebparagraph">Note that when we've expanded "Yes, we have no bananas" we have certainly
placed code into the tangled file from a different location; that will insert
a <code class="display"><span class="extract-syntax">#line</span></code> marker for the definition location; and we don't want the eventual
a <span class="extract"><span class="extract-syntax">#line</span></span> marker for the definition location; and we don't want the eventual
C compiler to think that the code which follows is also from that location.
So we insert a fresh line marker.
</p>
@ -284,11 +284,11 @@ page) and substitutes that, so that we end up with (say)
<span class="plain-syntax"> </span><span class="identifier-syntax">printf</span><span class="plain-syntax">(</span><span class="string-syntax">"This is build 5Q47.\n"</span><span class="plain-syntax">);</span>
</pre>
<p class="inwebparagraph">In some languages there are also special expansions (for example, in
InC <code class="display"><span class="extract-syntax">[[nonterminals]]</span></code> has a special meaning).
InC <span class="extract"><span class="extract-syntax">[[nonterminals]]</span></span> has a special meaning).
</p>
<p class="inwebparagraph">If the text in double-squares isn't recognised, that's not an error: it simply
passes straight through. So <code class="display"><span class="extract-syntax">[[water]]</span></code> becomes just <code class="display"><span class="extract-syntax">[[water]]</span></code>.
passes straight through. So <span class="extract"><span class="extract-syntax">[[water]]</span></span> becomes just <span class="extract"><span class="extract-syntax">[[water]]</span></span>.
</p>

24
docs/inweb/3-tw.html
View file

@ -54,14 +54,14 @@ to swarm a mass of individual weaves, or to make just a single weave, with the
target in each case being identified by its range. A further decoding layer
then translated each range into rather more basic details of what to weave and
where to put the result: and so we arrive at the front door of the routine
<code class="display"><span class="extract-syntax">Weaver::weave</span></code> below.
<span class="extract"><span class="extract-syntax">Weaver::weave</span></span> below.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Weaver::weave</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>Weaver::weave</b>:<br>The Swarm - <a href="1-ts.html#SP2">&#167;2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">weave_order</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wv</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax"> = </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax"> = </span><a href="5-wt.html#SP2" class="function-link"><span class="function-syntax">WeaveTree::new_tree</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wv</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">banner</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">banner</span><span class="plain-syntax">, </span><span class="string-syntax">"Weave of '%S' generated by Inweb"</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">booklet_title</span><span class="plain-syntax">);</span>
@ -90,7 +90,7 @@ where to put the result: and so we arrive at the front door of the routine
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP2" class="function-link"><span class="function-syntax">Errors::fatal_with_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"unable to write woven file"</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-fm.html#SP5" class="function-link"><span class="function-syntax">Formats::render</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">tree</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">STREAM_CLOSE</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP9" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-ti.html#SP8" class="function-link"><span class="function-syntax">Indexer::set_current_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">lines</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP1_1"></a><b>&#167;1.1. </b><code class="display">
@ -196,14 +196,14 @@ where to put the result: and so we arrive at the front door of the routine
<pre class="definitions">
<span class="definition-keyword">enum</span> <span class="constant-syntax">REGULAR_MATERIAL</span><span class="plain-syntax"> </span><span class="identifier-syntax">from</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">MACRO_MATERIAL</span><span class="plain-syntax"> </span><span class="comment"> when a macro is being defined...</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">DEFINITION_MATERIAL</span><span class="plain-syntax"> </span><span class="comment"> ...versus when an </span><code class="display"><span class="extract-syntax">@d</span></code><span class="comment"> definition is being made</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">DEFINITION_MATERIAL</span><span class="plain-syntax"> </span><span class="comment"> ...versus when an </span><span class="extract"><span class="extract-syntax">@d</span></span><span class="comment"> definition is being made</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CODE_MATERIAL</span><span class="plain-syntax"> </span><span class="comment"> verbatim code</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ENDNOTES_MATERIAL</span><span class="plain-syntax"> </span><span class="comment"> endnotes at the foot of a paragraph</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">FOOTNOTES_MATERIAL</span><span class="plain-syntax"> </span><span class="comment"> footnote texts for a paragraph</span>
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">weaver_state</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">kind_of_material</span><span class="plain-syntax">; </span><span class="comment"> one of the enumerated </span><code class="display"><span class="extract-syntax">*_MATERIAL</span></code><span class="comment"> constants above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">kind_of_material</span><span class="plain-syntax">; </span><span class="comment"> one of the enumerated </span><span class="extract"><span class="extract-syntax">*_MATERIAL</span></span><span class="comment"> constants above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">line_break_pending</span><span class="plain-syntax">; </span><span class="comment"> insert a line break before the next woven line?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">next_heading_without_vertical_skip</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">horizontal_rule_just_drawn</span><span class="plain-syntax">;</span>
@ -462,7 +462,7 @@ we only have to transcribe it. But not quite!
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="3-tw.html#SP5" class="function-link"><span class="function-syntax">Weaver::commentary_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">, </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ap</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3">&#167;2.7.2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_1_1"></a><b>&#167;2.7.2.3.1.1. </b>Displayed source is the material marked with <code class="display"><span class="extract-syntax">&gt;&gt;</span></code> arrows in column 1.
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3">&#167;2.7.2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_1_1"></a><b>&#167;2.7.2.3.1.1. </b>Displayed source is the material marked with <span class="extract"><span class="extract-syntax">&gt;&gt;</span></span> arrows in column 1.
</p>
@ -496,7 +496,7 @@ add a vertical skip between them to show the division more clearly.
<span class="plain-syntax"> </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3_1">&#167;2.7.2.3.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_1_3"></a><b>&#167;2.7.2.3.1.3. </b>Here our extension is simply to provide a tidier way to use TeX's standard
<code class="display"><span class="extract-syntax">\item</span></code> and <code class="display"><span class="extract-syntax">\itemitem</span></code> macros for indented list items.
<span class="extract"><span class="extract-syntax">\item</span></span> and <span class="extract"><span class="extract-syntax">\itemitem</span></span> macros for indented list items.
</p>
@ -565,7 +565,7 @@ in the source is set indented in code style.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">F</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">cued_already</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) </span><a href="1-pc.html#SP8" class="function-link"><span class="function-syntax">Main::error_in_web</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"footnote never cued"</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ap</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FN</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3_1">&#167;2.7.2.3.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_2"></a><b>&#167;2.7.2.3.2. Code-like matter. </b>Even though Inweb's approach, unlike <code class="display"><span class="extract-syntax">CWEB</span></code>'s, is to respect the layout
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3_1">&#167;2.7.2.3.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_2"></a><b>&#167;2.7.2.3.2. Code-like matter. </b>Even though Inweb's approach, unlike <span class="extract"><span class="extract-syntax">CWEB</span></span>'s, is to respect the layout
of the original, this is still quite typographically complex: commentary
and macro usage is rendered differently.
</p>
@ -615,7 +615,7 @@ and macro usage is rendered differently.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">prefatory</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ClumsyLabel:</span><span class="plain-syntax"> ;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3">&#167;2.7.2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_2_1"></a><b>&#167;2.7.2.3.2.1. </b>Code is typeset between the <code class="display"><span class="extract-syntax">\beginlines</span></code> and <code class="display"><span class="extract-syntax">\endlines</span></code> macros in TeX,
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3">&#167;2.7.2.3</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_2_1"></a><b>&#167;2.7.2.3.2.1. </b>Code is typeset between the <span class="extract"><span class="extract-syntax">\beginlines</span></span> and <span class="extract"><span class="extract-syntax">\endlines</span></span> macros in TeX,
hence the name of the following paragraph:
</p>
@ -682,7 +682,7 @@ otherwise, they are set flush right.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">part_before_comment</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">part_within_comment</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3_2">&#167;2.7.2.3.2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_2_4"></a><b>&#167;2.7.2.3.2.4. </b>Set the <code class="display"><span class="extract-syntax">@d</span></code> definition escape very slightly more fancily:
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3_2">&#167;2.7.2.3.2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_7_2_3_2_4"></a><b>&#167;2.7.2.3.2.4. </b>Set the <span class="extract"><span class="extract-syntax">@d</span></span> definition escape very slightly more fancily:
</p>
@ -753,7 +753,7 @@ otherwise, they are set flush right.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="3-tw.html#SP2_7_2_3_2">&#167;2.7.2.3.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Endnotes. </b>The endnotes describe function calls from far away, or unexpected
structure usage, or how <code class="display"><span class="extract-syntax">CWEB</span></code>-style code substitutions were made.
structure usage, or how <span class="extract"><span class="extract-syntax">CWEB</span></span>-style code substitutions were made.
</p>
<pre class="displayed-code all-displayed-code">
@ -1018,7 +1018,7 @@ structure usage, or how <code class="display"><span class="extract-syntax">CWEB<
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">use</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Section tables of contents. </b>These appear at the top of each woven section, and give links to the paragraphs
marked as <code class="display"><span class="extract-syntax">@h</span></code> headings.
marked as <span class="extract"><span class="extract-syntax">@h</span></span> headings.
</p>
<pre class="displayed-code all-displayed-code">

4
docs/inweb/3-twot.html
View file

@ -48,8 +48,8 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="3-twot.html#SP1">&#167;1. Commentary text</a></li><li><a href="3-twot.html#SP3">&#167;3. Code text</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Commentary text. </b>The following takes text, divides it up at stroke-mark boundaries &mdash;
that is, <code class="display"><span class="extract-syntax">this is inside</span></code>, this is outside &mdash; and sends contiguous pieces
of it either to <code class="display"><span class="extract-syntax">TextWeaver::inline_code_fragment</span></code> or <code class="display"><span class="extract-syntax">TextWeaver::commentary_fragment</span></code>
that is, <span class="extract"><span class="extract-syntax">this is inside</span></span>, this is outside &mdash; and sends contiguous pieces
of it either to <span class="extract"><span class="extract-syntax">TextWeaver::inline_code_fragment</span></span> or <span class="extract"><span class="extract-syntax">TextWeaver::commentary_fragment</span></span>
as appropriate.
</p>

6
docs/inweb/4-as.html
View file

@ -99,8 +99,8 @@ actually called ACME: the 6502 assembler of the same name.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/2-mth.html#SP6" class="function-link"><span class="function-syntax">Methods::provided</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">methods</span><span class="plain-syntax">, </span><span class="constant-syntax">SYNTAX_COLOUR_WEA_MTID</span><span class="plain-syntax">) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">METHOD_ADD</span><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">SYNTAX_COLOUR_WEA_MTID</span><span class="plain-syntax">, </span><a href="4-as.html#SP10" class="function-link"><span class="function-syntax">ACMESupport::syntax_colour</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>This utility does a very limited <code class="display"><span class="extract-syntax">WRITE</span></code>-like job. (We don't want to use
the actual <code class="display"><span class="extract-syntax">WRITE</span></code> because that would make it possible for malicious language
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>This utility does a very limited <span class="extract"><span class="extract-syntax">WRITE</span></span>-like job. (We don't want to use
the actual <span class="extract"><span class="extract-syntax">WRITE</span></span> because that would make it possible for malicious language
files to crash Inweb.)
</p>
@ -300,7 +300,7 @@ files to crash Inweb.)
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>The following is an opportunity for us to scold the author for any
violation of the namespace rules. We're going to look for functions named
<code class="display"><span class="extract-syntax">Whatever::name()</span></code> whose definitions are not in the <code class="display"><span class="extract-syntax">Whatever::</span></code> section;
<span class="extract"><span class="extract-syntax">Whatever::name()</span></span> whose definitions are not in the <span class="extract"><span class="extract-syntax">Whatever::</span></span> section;
in other words, we police the rule that functions actually are defined in the
namespace which their names imply. This can be turned off with a special
bibliographic variable, but don't do that.

60
docs/inweb/4-cl.html
View file

@ -87,10 +87,10 @@ The structure definitions in this Inweb web all take the required form,
of course, and provide many more examples.
</p>
<p class="inwebparagraph">Note that a <code class="display"><span class="extract-syntax">fruit</span></code> structure contains a <code class="display"><span class="extract-syntax">pip</span></code> structure (in fact, five of
them), but only contains pointers to <code class="display"><span class="extract-syntax">tree_species</span></code> structures and itself.
C requires therefore that the structure definition for <code class="display"><span class="extract-syntax">pip</span></code> must occur
earlier in the code than that for <code class="display"><span class="extract-syntax">fruit</span></code>. This is a nuisance, so Inweb
<p class="inwebparagraph">Note that a <span class="extract"><span class="extract-syntax">fruit</span></span> structure contains a <span class="extract"><span class="extract-syntax">pip</span></span> structure (in fact, five of
them), but only contains pointers to <span class="extract"><span class="extract-syntax">tree_species</span></span> structures and itself.
C requires therefore that the structure definition for <span class="extract"><span class="extract-syntax">pip</span></span> must occur
earlier in the code than that for <span class="extract"><span class="extract-syntax">fruit</span></span>. This is a nuisance, so Inweb
takes care of it automatically.
</p>
@ -128,7 +128,7 @@ the sake of an illustrative example, let's suppose that line is:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> unsigned long long int *val;</span>
</pre>
<p class="inwebparagraph">We need to extract the element name, <code class="display"><span class="extract-syntax">val</span></code>, and make a note of it.
<p class="inwebparagraph">We need to extract the element name, <span class="extract"><span class="extract-syntax">val</span></span>, and make a note of it.
</p>
@ -155,7 +155,7 @@ the sake of an illustrative example, let's suppose that line is:
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">p</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_1"></a><b>&#167;2.1.1.1. </b>The following reduces <code class="display"><span class="extract-syntax">unsigned long long int *val;</span></code> to just <code class="display"><span class="extract-syntax">int *val;</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1">&#167;2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_1"></a><b>&#167;2.1.1.1. </b>The following reduces <span class="extract"><span class="extract-syntax">unsigned long long int *val;</span></span> to just <span class="extract"><span class="extract-syntax">int *val;</span></span>.
</p>
@ -177,8 +177,8 @@ the sake of an illustrative example, let's suppose that line is:
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_2"></a><b>&#167;2.1.1.2. </b>At this point <code class="display"><span class="extract-syntax">p</span></code> has been reduced to <code class="display"><span class="extract-syntax">int *val;</span></code>, but the following moves
<code class="display"><span class="extract-syntax">pos</span></code> to point to the <code class="display"><span class="extract-syntax">*</span></code>:
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_2"></a><b>&#167;2.1.1.2. </b>At this point <span class="extract"><span class="extract-syntax">p</span></span> has been reduced to <span class="extract"><span class="extract-syntax">int *val;</span></span>, but the following moves
<span class="extract"><span class="extract-syntax">pos</span></span> to point to the <span class="extract"><span class="extract-syntax">*</span></span>:
</p>
@ -189,7 +189,7 @@ the sake of an illustrative example, let's suppose that line is:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> ((</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">)) &amp;&amp; (</span><a href="../foundation-module/4-chr.html#SP2" class="function-link"><span class="function-syntax">Characters::is_space_or_tab</span></a><span class="plain-syntax">(</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">)) == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pos</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP11" class="function-link"><span class="function-syntax">Str::forward</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_3"></a><b>&#167;2.1.1.3. </b>And this moves it past the <code class="display"><span class="extract-syntax">*</span></code> to point to the <code class="display"><span class="extract-syntax">v</span></code> in <code class="display"><span class="extract-syntax">int *val;</span></code>:
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_3"></a><b>&#167;2.1.1.3. </b>And this moves it past the <span class="extract"><span class="extract-syntax">*</span></span> to point to the <span class="extract"><span class="extract-syntax">v</span></span> in <span class="extract"><span class="extract-syntax">int *val;</span></span>:
</p>
@ -200,8 +200,8 @@ the sake of an illustrative example, let's suppose that line is:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> ((</span><a href="../foundation-module/4-chr.html#SP2" class="function-link"><span class="function-syntax">Characters::is_space_or_tab</span></a><span class="plain-syntax">(</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">))) || (</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">) == </span><span class="character-syntax">'*'</span><span class="plain-syntax">) ||</span>
<span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">) == </span><span class="character-syntax">'('</span><span class="plain-syntax">) || (</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">) == </span><span class="character-syntax">')'</span><span class="plain-syntax">)) </span><span class="identifier-syntax">pos</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP11" class="function-link"><span class="function-syntax">Str::forward</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_4"></a><b>&#167;2.1.1.4. </b>This then first copies the substring <code class="display"><span class="extract-syntax">val;</span></code> into <code class="display"><span class="extract-syntax">elname</span></code>, then cuts that
down to just the identifier characters at the front, i.e., to <code class="display"><span class="extract-syntax">val</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1_4"></a><b>&#167;2.1.1.4. </b>This then first copies the substring <span class="extract"><span class="extract-syntax">val;</span></span> into <span class="extract"><span class="extract-syntax">elname</span></span>, then cuts that
down to just the identifier characters at the front, i.e., to <span class="extract"><span class="extract-syntax">val</span></span>.
</p>
@ -212,14 +212,14 @@ down to just the identifier characters at the front, i.e., to <code class="displ
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP26" class="function-link"><span class="function-syntax">Str::substr</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">elname</span><span class="plain-syntax">, </span><span class="identifier-syntax">pos</span><span class="plain-syntax">, </span><a href="../foundation-module/4-sm.html#SP10" class="function-link"><span class="function-syntax">Str::end</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">p</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-pm.html#SP10" class="function-link"><span class="function-syntax">Regexp::match</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">elname</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%i+)%c*"</span><span class="plain-syntax">)) </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">elname</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_2"></a><b>&#167;2.2. Structure dependency. </b>We say that S depends on T if <code class="display"><span class="extract-syntax">struct S</span></code> has an element whose type is
<code class="display"><span class="extract-syntax">struct T</span></code>. That matters because if so then <code class="display"><span class="extract-syntax">struct T</span></code> has to be defined
before <code class="display"><span class="extract-syntax">struct S</span></code> in the tangled output.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_1_1">&#167;2.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP2_2"></a><b>&#167;2.2. Structure dependency. </b>We say that S depends on T if <span class="extract"><span class="extract-syntax">struct S</span></span> has an element whose type is
<span class="extract"><span class="extract-syntax">struct T</span></span>. That matters because if so then <span class="extract"><span class="extract-syntax">struct T</span></span> has to be defined
before <span class="extract"><span class="extract-syntax">struct S</span></span> in the tangled output.
</p>
<p class="inwebparagraph">It's important to note that <code class="display"><span class="extract-syntax">struct S</span></code> merely having a member of type
<code class="display"><span class="extract-syntax">struct *T</span></code> does not create a dependency. In the code below, because <code class="display"><span class="extract-syntax">%i</span></code>
matches only identifier characters and <code class="display"><span class="extract-syntax">*</span></code> is not one of those, a line like
<p class="inwebparagraph">It's important to note that <span class="extract"><span class="extract-syntax">struct S</span></span> merely having a member of type
<span class="extract"><span class="extract-syntax">struct *T</span></span> does not create a dependency. In the code below, because <span class="extract"><span class="extract-syntax">%i</span></span>
matches only identifier characters and <span class="extract"><span class="extract-syntax">*</span></span> is not one of those, a line like
</p>
<pre class="displayed-code all-displayed-code">
@ -256,7 +256,7 @@ matches only identifier characters and <code class="display"><span class="extrac
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">str</span><span class="plain-syntax"> != </span><span class="identifier-syntax">current_str</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">used_structure</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">structure_name</span><span class="plain-syntax">)))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">str</span><span class="plain-syntax">, </span><span class="reserved-syntax">language_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_str</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">incorporates</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_2">&#167;2.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Functions. </b>This time, we will need to keep track of <code class="display"><span class="extract-syntax">#ifdef</span></code> and <code class="display"><span class="extract-syntax">#endif</span></code> pairs
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP2_2">&#167;2.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Functions. </b>This time, we will need to keep track of <span class="extract"><span class="extract-syntax">#ifdef</span></span> and <span class="extract"><span class="extract-syntax">#endif</span></span> pairs
in the source. This matters because we will want to predeclare functions;
but if functions are declared in conditional compilation, then their
predeclarations have to be made under the same conditions.
@ -314,8 +314,8 @@ source line being scanned lies within.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> type identifier(args...</span>
</pre>
<p class="inwebparagraph">where we parse <code class="display"><span class="extract-syntax">type</span></code> only minimally. In InC (only), the identifier can
contain namespace dividers written <code class="display"><span class="extract-syntax">::</span></code>. Function declarations, we will assume,
<p class="inwebparagraph">where we parse <span class="extract"><span class="extract-syntax">type</span></span> only minimally. In InC (only), the identifier can
contain namespace dividers written <span class="extract"><span class="extract-syntax">::</span></span>. Function declarations, we will assume,
always begin on column 1 of their source files, and we expect them to take
modern ANSI C style, not the long-deprecated late 1970s C style.
</p>
@ -349,7 +349,7 @@ modern ANSI C style, not the long-deprecated late 1970s C style.
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_2_1"></a><b>&#167;3.2.1. </b>C has a whole soup of reserved words applying to types, but most of them
can't apply to the return type of a function. We do, however, iterate so that
forms like <code class="display"><span class="extract-syntax">static long long int</span></code> will work.
forms like <span class="extract"><span class="extract-syntax">static long long int</span></span> will work.
</p>
@ -392,9 +392,9 @@ forms like <code class="display"><span class="extract-syntax">static long long i
<span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="identifier-syntax">World::Subjects::make_adj_const_domain</span><span class="plain-syntax">(</span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> *</span><span class="identifier-syntax">infs</span><span class="plain-syntax">,|</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">instance</span><span class="plain-syntax"> *</span><span class="identifier-syntax">nc</span><span class="plain-syntax">, </span><span class="identifier-syntax">property</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prn</span><span class="plain-syntax">) {|</span>
</pre>
<p class="inwebparagraph">Having read the first line, <code class="display"><span class="extract-syntax">arguments</span></code> would contain <code class="display"><span class="extract-syntax">inference_subject *infs,</span></code>
<p class="inwebparagraph">Having read the first line, <span class="extract"><span class="extract-syntax">arguments</span></span> would contain <span class="extract"><span class="extract-syntax">inference_subject *infs,</span></span>
and would thus be incomplete. We continue across subsequent lines until we
reach an open brace <code class="display"><span class="extract-syntax">{</span></code>.
reach an open brace <span class="extract"><span class="extract-syntax">{</span></span>.
</p>
@ -425,7 +425,7 @@ reach an open brace <code class="display"><span class="extract-syntax">{</span><
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">n</span><span class="plain-syntax"> &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::truncate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">arguments</span><span class="plain-syntax">, </span><span class="identifier-syntax">n</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-cl.html#SP3_2_2">&#167;3.2.2</a>.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Subcategorisation. </b>The following is called after the parser gives every line in the web a
category; we can, if we wish, change that for a more exotic one. We simply
look for a <code class="display"><span class="extract-syntax">#include</span></code> of one of the ANSI C standard libraries.
look for a <span class="extract"><span class="extract-syntax">#include</span></span> of one of the ANSI C standard libraries.
</p>
<pre class="displayed-code all-displayed-code">
@ -447,11 +447,11 @@ look for a <code class="display"><span class="extract-syntax">#include</span></c
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Tangling extras. </b>"Additional early matter" is used for the inclusions of the ANSI library
files. We need to do that early, because otherwise types declared in them
(such as <code class="display"><span class="extract-syntax">FILE</span></code>) won't exist in time for the structure definitions we will
(such as <span class="extract"><span class="extract-syntax">FILE</span></span>) won't exist in time for the structure definitions we will
be tangling next.
</p>
<p class="inwebparagraph">It might seem reasonable to move all <code class="display"><span class="extract-syntax">#include</span></code> files up front this way,
<p class="inwebparagraph">It might seem reasonable to move all <span class="extract"><span class="extract-syntax">#include</span></span> files up front this way,
not just the ANSI ones. But that would defeat any conditional compilation
around the inclusions; which Inform (for instance) needs in order to make
platform-specific details to handle directories without POSIX in Windows.
@ -482,7 +482,7 @@ structures.
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Predeclare the functions</span> <span class="named-paragraph-number">6.4</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6_1"></a><b>&#167;6.1. </b>A "simple typedef" here means one that is aliasing something other than
a structure: for example <code class="display"><span class="extract-syntax">typedef unsigned int uint;</span></code> would be a simple typedef.
a structure: for example <span class="extract"><span class="extract-syntax">typedef unsigned int uint;</span></span> would be a simple typedef.
</p>
@ -504,8 +504,8 @@ a structure: for example <code class="display"><span class="extract-syntax">type
precede outer, but we need to be careful to be terminating if the source
code we're given is not well founded because of an error by its programmer:
for example, that structure A contains B contains C contains A. We do this
with the <code class="display"><span class="extract-syntax">tangled</span></code> flag, which is <code class="display"><span class="extract-syntax">FALSE</span></code> if a structure hasn't been
started yet, <code class="display"><span class="extract-syntax">NOT_APPLICABLE</span></code> if it's in progress, and <code class="display"><span class="extract-syntax">TRUE</span></code> if it's
with the <span class="extract"><span class="extract-syntax">tangled</span></span> flag, which is <span class="extract"><span class="extract-syntax">FALSE</span></span> if a structure hasn't been
started yet, <span class="extract"><span class="extract-syntax">NOT_APPLICABLE</span></span> if it's in progress, and <span class="extract"><span class="extract-syntax">TRUE</span></span> if it's
finished.
</p>
@ -541,7 +541,7 @@ finished.
<span class="plain-syntax"> </span><a href="2-tgs.html#SP7" class="function-link"><span class="function-syntax">Tags::close_ifdefs</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">str</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">structure_header_at</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">owning_paragraph</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6_4"></a><b>&#167;6.4. </b>Functions are rather easier to deal with. In general, if a function was
defined within some number of nested <code class="display"><span class="extract-syntax">#ifdef</span></code> or <code class="display"><span class="extract-syntax">#ifndef</span></code> directives, then
defined within some number of nested <span class="extract"><span class="extract-syntax">#ifdef</span></span> or <span class="extract"><span class="extract-syntax">#ifndef</span></span> directives, then
we reproduce those around the predeclaration: except, as a special trick,
if the line contains a particular comment. For example:
</p>

132
docs/inweb/4-is.html
View file

@ -106,13 +106,13 @@ all of those methods, it has a whole lot more of its own.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3_1"></a><b>&#167;3.1. Parsing Preform grammar. </b>This is where we look for declarations of nonterminals. Very little about
the following code will make sense unless you've first read the Preform
section of the <code class="display"><span class="extract-syntax">words</span></code> module, which is what we're supporting, and seen
section of the <span class="extract"><span class="extract-syntax">words</span></span> module, which is what we're supporting, and seen
some examples of Preform being used in the Inform source code.
</p>
<p class="inwebparagraph">In parsing, we categorise the opening lines <code class="display"><span class="extract-syntax">PREFORM_LCAT</span></code>. Subsequent lines
of grammar are <code class="display"><span class="extract-syntax">PREFORM_GRAMMAR_LCAT</span></code>; but the lines of InC code inside an
<code class="display"><span class="extract-syntax">internal</span></code> definition remain just plain <code class="display"><span class="extract-syntax">CODE_BODY_LCAT</span></code> lines.
<p class="inwebparagraph">In parsing, we categorise the opening lines <span class="extract"><span class="extract-syntax">PREFORM_LCAT</span></span>. Subsequent lines
of grammar are <span class="extract"><span class="extract-syntax">PREFORM_GRAMMAR_LCAT</span></span>; but the lines of InC code inside an
<span class="extract"><span class="extract-syntax">internal</span></span> definition remain just plain <span class="extract"><span class="extract-syntax">CODE_BODY_LCAT</span></span> lines.
</p>
@ -135,9 +135,9 @@ of grammar are <code class="display"><span class="extract-syntax">PREFORM_GRAMMA
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">form</span><span class="plain-syntax"> != </span><span class="constant-syntax">NOT_A_NONTERMINAL</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">Record a Preform nonterminal here</span> <span class="named-paragraph-number">3.1.3</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pntname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">header</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_1_1"></a><b>&#167;3.1.1. </b>The keyword <code class="display"><span class="extract-syntax">internal</span></code> can be followed by an indication of the number
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3">&#167;3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_1_1"></a><b>&#167;3.1.1. </b>The keyword <span class="extract"><span class="extract-syntax">internal</span></span> can be followed by an indication of the number
of words the nonterminal will match: usually a decimal non-negative number,
but optionally a question mark <code class="display"><span class="extract-syntax">?</span></code> to indicate voracity.
but optionally a question mark <span class="extract"><span class="extract-syntax">?</span></span> to indicate voracity.
</p>
@ -172,14 +172,14 @@ structures to be created:
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">preform_nonterminal</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">nt_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">&lt;action-clause&gt;</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">unangled_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">action-clause</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_C_identifier</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">action_clause_NTM</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">nt_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">&lt;action-clause&gt;</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">unangled_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">action-clause</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">as_C_identifier</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">action_clause_NTM</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">as_function</span><span class="plain-syntax">; </span><span class="comment"> defined internally, that is, parsed by a C language_function</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">voracious</span><span class="plain-syntax">; </span><span class="comment"> a voracious nonterminal: see "The English Syntax of Inform"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">min_word_count</span><span class="plain-syntax">; </span><span class="comment"> for internals only</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">max_word_count</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">takes_pointer_result</span><span class="plain-syntax">; </span><span class="comment"> right-hand formula defines </span><code class="display"><span class="extract-syntax">*XP</span></code><span class="comment">, not </span><code class="display"><span class="extract-syntax">*X</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">takes_pointer_result</span><span class="plain-syntax">; </span><span class="comment"> right-hand formula defines </span><span class="extract"><span class="extract-syntax">*XP</span></span><span class="comment">, not </span><span class="extract"><span class="extract-syntax">*X</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">where_defined</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">preform_nonterminal</span><span class="plain-syntax"> *</span><span class="identifier-syntax">next_pnt_alphabetically</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
@ -297,17 +297,17 @@ the following definition:
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Preform_theme</span><span class="plain-syntax">) </span><a href="2-tgs.html#SP3" class="function-link"><span class="function-syntax">Tags::add_to_paragraph</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">owning_paragraph</span><span class="plain-syntax">, </span><span class="identifier-syntax">Preform_theme</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">category</span><span class="plain-syntax"> = </span><span class="constant-syntax">PREFORM_LCAT</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text_operand</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">header</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_1_3">&#167;3.1.3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_1_1_1"></a><b>&#167;3.1.1.1. Parsing the body of Preform grammar. </b>After a line like <code class="display"><span class="extract-syntax">&lt;action-clause&gt; ::=</span></code>, Preform grammar follows on subsequent
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_1_3">&#167;3.1.3</a>.</li></ul><p class="inwebparagraph"><a id="SP3_1_1_1"></a><b>&#167;3.1.1.1. Parsing the body of Preform grammar. </b>After a line like <span class="extract"><span class="extract-syntax">&lt;action-clause&gt; ::=</span></span>, Preform grammar follows on subsequent
lines until we hit the end of the paragraph, or a white-space line, whichever
comes first. Each line of grammar is categorised <code class="display"><span class="extract-syntax">PREFORM_GRAMMAR_LCAT</span></code>.
comes first. Each line of grammar is categorised <span class="extract"><span class="extract-syntax">PREFORM_GRAMMAR_LCAT</span></span>.
If we have a line with an arrow, like so:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> porcupine tree ==&gt; 2</span>
</pre>
<p class="inwebparagraph">then the text on the left goes into <code class="display"><span class="extract-syntax">text_operand</span></code> and the right into
<code class="display"><span class="extract-syntax">text_operand2</span></code>, with the arrow itself (and white space around it) cut out.
<p class="inwebparagraph">then the text on the left goes into <span class="extract"><span class="extract-syntax">text_operand</span></span> and the right into
<span class="extract"><span class="extract-syntax">text_operand2</span></span>, with the arrow itself (and white space around it) cut out.
</p>
@ -354,8 +354,8 @@ trust me, it's correct.
<span class="plain-syntax"> </span><span class="identifier-syntax">AL</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text_operand</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP3_1_1_1_2"></a><b>&#167;3.1.1.1.2. </b>Note that nonterminal variables are, by default, integers. If their names
are divided internally with a colon, however, as <code class="display"><span class="extract-syntax">&lt;&lt;structure:name&gt;&gt;</span></code>, then
they have the type <code class="display"><span class="extract-syntax">structure *</span></code>.
are divided internally with a colon, however, as <span class="extract"><span class="extract-syntax">&lt;&lt;structure:name&gt;&gt;</span></span>, then
they have the type <span class="extract"><span class="extract-syntax">structure *</span></span>.
</p>
@ -385,15 +385,15 @@ they have the type <code class="display"><span class="extract-syntax">structure
<span class="character-syntax"> DISCARD_TEXT(to_scan);</span>
<span class="character-syntax"> Regexp::dispose_of(&amp;mr);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul><p class="inwebparagraph"><a id="SP3_1_1_1_2_1"></a><b>&#167;3.1.1.1.2.1. </b>Nonterminal variables are actually just global C variables, and their C
identifiers need to avoid hyphens and colons. For example, <code class="display"><span class="extract-syntax">&lt;&lt;kind:ref&gt;&gt;</span></code>
has identifier <code class="display"><span class="extract-syntax">"kind_ref_NTMV"</span></code>. Each one is recorded in a structure thus:
identifiers need to avoid hyphens and colons. For example, <span class="extract"><span class="extract-syntax">&lt;&lt;kind:ref&gt;&gt;</span></span>
has identifier <span class="extract"><span class="extract-syntax">"kind_ref_NTMV"</span></span>. Each one is recorded in a structure thus:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">nonterminal_variable</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ntv_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"num"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ntv_type</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"int"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ntv_identifier</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"num_NTMV"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ntv_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"num"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ntv_type</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"int"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ntv_identifier</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"num_NTMV"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">first_mention</span><span class="plain-syntax">; </span><span class="comment"> first usage</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">nonterminal_variable</span><span class="plain-syntax">;</span>
@ -412,7 +412,7 @@ has identifier <code class="display"><span class="extract-syntax">"kind_ref_NTMV
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">ntv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ntv_identifier</span><span class="plain-syntax">, </span><span class="string-syntax">"%S_NTMV"</span><span class="plain-syntax">, </span><span class="identifier-syntax">var_given</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ntv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">first_mention</span><span class="plain-syntax"> = </span><span class="identifier-syntax">AL</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_1_1_1_2">&#167;3.1.1.1.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3_2"></a><b>&#167;3.2. Parsing I-literals. </b>A simpler but useful further addition to C is that we recognise a new form
of string literal: <code class="display"><span class="extract-syntax">I"quartz"</span></code> makes a constant text stream with the content
of string literal: <span class="extract"><span class="extract-syntax">I"quartz"</span></span> makes a constant text stream with the content
"quartz".
</p>
@ -447,8 +447,8 @@ of string literal: <code class="display"><span class="extract-syntax">I"quartz"<
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ended</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">This is definitely an I-literal</span> <span class="named-paragraph-number">3.2.1.2</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">lit</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_2">&#167;3.2</a>.</li></ul><p class="inwebparagraph"><a id="SP3_2_1_1"></a><b>&#167;3.2.1.1. </b>Each I-literal results in an instance of the following being created. The
I-literal <code class="display"><span class="extract-syntax">I"quartz"</span></code> would have content <code class="display"><span class="extract-syntax">quartz</span></code> and identifier something
like <code class="display"><span class="extract-syntax">TL_IS_123</span></code>.
I-literal <span class="extract"><span class="extract-syntax">I"quartz"</span></span> would have content <span class="extract"><span class="extract-syntax">quartz</span></span> and identifier something
like <span class="extract"><span class="extract-syntax">TL_IS_123</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -464,7 +464,7 @@ like <code class="display"><span class="extract-syntax">TL_IS_123</span></code>.
<span class="plain-syntax"> text_stream *T = I"quartz";</span>
</pre>
<p class="inwebparagraph">We create the necessary I-literal, and splice the line so that it now reads
<code class="display"><span class="extract-syntax">text_stream *T = TL_IS_123;</span></code>. (That's why we don't call any of this on a
<span class="extract"><span class="extract-syntax">text_stream *T = TL_IS_123;</span></span>. (That's why we don't call any of this on a
weave run; we're actually amending the code of the web.)
</p>
@ -489,7 +489,7 @@ weave run; we're actually amending the code of the web.)
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">L</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">after</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">before</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">after</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_2_1">&#167;3.2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Tangling methods. </b>Suppress the expansion of macros occurring on a line introduced by a <code class="display"><span class="extract-syntax">//</span></code>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP3_2_1">&#167;3.2.1</a>.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Tangling methods. </b>Suppress the expansion of macros occurring on a line introduced by a <span class="extract"><span class="extract-syntax">//</span></span>
comment. (This avoids problems when tangling code that's been commented out.)
</p>
@ -500,8 +500,8 @@ comment. (This avoids problems when tangling code that's been commented out.)
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>InC does three things which C doesn't: it allows the namespaced function
names like <code class="display"><span class="extract-syntax">Section::function()</span></code>; it allows Foundation-class-style string
literals marked with an I, <code class="display"><span class="extract-syntax">I"like this"</span></code>, which we will call I-literals;
names like <span class="extract"><span class="extract-syntax">Section::function()</span></span>; it allows Foundation-class-style string
literals marked with an I, <span class="extract"><span class="extract-syntax">I"like this"</span></span>, which we will call I-literals;
and it allows Preform natural language grammar to be mixed in with code.
</p>
@ -509,13 +509,13 @@ and it allows Preform natural language grammar to be mixed in with code.
two special tangling commands:
</p>
<ul class="items"><li>(a) <code class="display"><span class="extract-syntax">[[nonterminals]]</span></code> tangles to code which initialises the Preform
<ul class="items"><li>(a) <span class="extract"><span class="extract-syntax">[[nonterminals]]</span></span> tangles to code which initialises the Preform
grammar. (The grammar defines the meaning of nonterminals such as
<code class="display"><span class="extract-syntax">&lt;sentence&gt;</span></code>. They're not terminal in the sense that they are defined
<span class="extract"><span class="extract-syntax">&lt;sentence&gt;</span></span>. They're not terminal in the sense that they are defined
as combinations of other things.) In practice, this needs to appear once
in any program using Preform. For the Inform project, that's done in the
<code class="display"><span class="extract-syntax">words</span></code> module of the Inform 7 compiler.
</li><li>(b) <code class="display"><span class="extract-syntax">[[textliterals]]</span></code> tangles to code which initialises the I-literals.
<span class="extract"><span class="extract-syntax">words</span></span> module of the Inform 7 compiler.
</li><li>(b) <span class="extract"><span class="extract-syntax">[[textliterals]]</span></span> tangles to code which initialises the I-literals.
</p>
<pre class="displayed-code all-displayed-code">
@ -533,12 +533,12 @@ in any program using Preform. For the Inform project, that's done in the
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Time to predeclare things. InC is going to create a special function, right
at the end of the code, which "registers" the nonterminals, creating their
run-time data structures; we must predeclare this function. It will set values
for the pointers <code class="display"><span class="extract-syntax">action_clause_NTM</span></code>, and so on; these are global variables,
which we initially declare as <code class="display"><span class="extract-syntax">NULL</span></code>.
for the pointers <span class="extract"><span class="extract-syntax">action_clause_NTM</span></span>, and so on; these are global variables,
which we initially declare as <span class="extract"><span class="extract-syntax">NULL</span></span>.
</p>
<p class="inwebparagraph">We also declare the nonterminal variables like <code class="display"><span class="extract-syntax">kind_ref_NTMV</span></code>, initialising
all integers to zero and all pointers to <code class="display"><span class="extract-syntax">NULL</span></code>.
<p class="inwebparagraph">We also declare the nonterminal variables like <span class="extract"><span class="extract-syntax">kind_ref_NTMV</span></span>, initialising
all integers to zero and all pointers to <span class="extract"><span class="extract-syntax">NULL</span></span>.
</p>
<p class="inwebparagraph">We do something similar, but simpler, to declare text stream constants.
@ -604,7 +604,7 @@ They make use of macros and data structures defined in the Inform 7 web.
to how to tangle the lines we've given special categories to.
</p>
<p class="inwebparagraph">We need to tangle <code class="display"><span class="extract-syntax">PREFORM_LCAT</span></code> lines (those holding nonterminal declarations)
<p class="inwebparagraph">We need to tangle <span class="extract"><span class="extract-syntax">PREFORM_LCAT</span></span> lines (those holding nonterminal declarations)
in a special way...
</p>
@ -626,9 +626,9 @@ In the case of an internal definition, like
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">k_kind_for_template_NTM</span><span class="plain-syntax">(</span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">X</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> **</span><span class="identifier-syntax">XP</span><span class="plain-syntax">) {</span>
</pre>
<p class="inwebparagraph">that is, to a function which returns <code class="display"><span class="extract-syntax">TRUE</span></code> if it makes a match on the text
excerpt in Inform's source text, <code class="display"><span class="extract-syntax">FALSE</span></code> otherwise; if it matches and produces
an integer and/or pointer result, these are copied into <code class="display"><span class="extract-syntax">*X</span></code> and <code class="display"><span class="extract-syntax">*XP</span></code>. The
<p class="inwebparagraph">that is, to a function which returns <span class="extract"><span class="extract-syntax">TRUE</span></span> if it makes a match on the text
excerpt in Inform's source text, <span class="extract"><span class="extract-syntax">FALSE</span></span> otherwise; if it matches and produces
an integer and/or pointer result, these are copied into <span class="extract"><span class="extract-syntax">*X</span></span> and <span class="extract"><span class="extract-syntax">*XP</span></span>. The
remaining lines of the function are tangled unaltered, i.e., following the
same rules as for the body of any other C function.
</p>
@ -659,16 +659,16 @@ Thus the opening line
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">action_clause_NTMC</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">X</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> **</span><span class="identifier-syntax">XP</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> **</span><span class="identifier-syntax">RP</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> *</span><span class="identifier-syntax">FW</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
</pre>
<p class="inwebparagraph">Subsequent lines of the nonterminal are categorised <code class="display"><span class="extract-syntax">PREFORM_GRAMMAR_LCAT</span></code>
<p class="inwebparagraph">Subsequent lines of the nonterminal are categorised <span class="extract"><span class="extract-syntax">PREFORM_GRAMMAR_LCAT</span></span>
and thus won't tangle to code at all, by the usual rules; so we tangle from
them directly here.
</p>
<p class="inwebparagraph">Composition is what happens after a successful match of the text in the
word range <code class="display"><span class="extract-syntax">W</span></code>. The idea is that, especially if the pattern was
word range <span class="extract"><span class="extract-syntax">W</span></span>. The idea is that, especially if the pattern was
complicated, we will need to "compose" the results of parsing individual
pieces of it into a result for the whole. These partial results can be found
in the arrays <code class="display"><span class="extract-syntax">R[n]</span></code> and <code class="display"><span class="extract-syntax">RP[n]</span></code> passed as parameters; recall that every
in the arrays <span class="extract"><span class="extract-syntax">R[n]</span></span> and <span class="extract"><span class="extract-syntax">RP[n]</span></span> passed as parameters; recall that every
nonterminal has in principle both an integer and a pointer result, though
often one or both is undefined.
</p>
@ -680,8 +680,8 @@ often one or both is undefined.
<span class="plain-syntax"> &lt;cardinal-number&gt; + &lt;cardinal-number&gt; ==&gt; R[1] + R[2]</span>
</pre>
<p class="inwebparagraph">where the composition function would be called on a match of, say, "\(5 + 7\)",
and would find the values 5 and 7 in <code class="display"><span class="extract-syntax">R[1]</span></code> and <code class="display"><span class="extract-syntax">R[2]</span></code> respectively. It would
then add these together, store 12 in <code class="display"><span class="extract-syntax">*X</span></code>, and return <code class="display"><span class="extract-syntax">TRUE</span></code> to show that all
and would find the values 5 and 7 in <span class="extract"><span class="extract-syntax">R[1]</span></span> and <span class="extract"><span class="extract-syntax">R[2]</span></span> respectively. It would
then add these together, store 12 in <span class="extract"><span class="extract-syntax">*X</span></span>, and return <span class="extract"><span class="extract-syntax">TRUE</span></span> to show that all
was well.
</p>
@ -693,10 +693,10 @@ was well.
</pre>
<p class="inwebparagraph">which says that the composite result &mdash; the right-hand formula &mdash; is formed by
calling a particular routine on the integer result of subexpression 2
(<code class="display"><span class="extract-syntax">&lt;k-formal-kind-variable&gt;</span></code>) and the pointer result of subexpression 1
(<code class="display"><span class="extract-syntax">&lt;k-kind-of-kind&gt;</span></code>). The answer, the composite result, that is, must be
placed in <code class="display"><span class="extract-syntax">*X</span></code> and <code class="display"><span class="extract-syntax">*XP</span></code>. (Composition functions are also allowed to
invalidate the result, by returning <code class="display"><span class="extract-syntax">FALSE</span></code>, and have other tricks up their
(<span class="extract"><span class="extract-syntax">&lt;k-formal-kind-variable&gt;</span></span>) and the pointer result of subexpression 1
(<span class="extract"><span class="extract-syntax">&lt;k-kind-of-kind&gt;</span></span>). The answer, the composite result, that is, must be
placed in <span class="extract"><span class="extract-syntax">*X</span></span> and <span class="extract"><span class="extract-syntax">*XP</span></span>. (Composition functions are also allowed to
invalidate the result, by returning <span class="extract"><span class="extract-syntax">FALSE</span></span>, and have other tricks up their
sleeves, but none of that is handled by Inweb: see the Inform 7 web for more
on this.)
</p>
@ -716,7 +716,7 @@ on this.)
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">needs_collation</span><span class="plain-syntax">) </span>&lt;<span class="named-paragraph">At least one of the grammar lines provided an arrow and formula</span> <span class="named-paragraph-number">9.1.2</span>&gt;
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span>&lt;<span class="named-paragraph">None of the grammar lines provided an arrow and formula</span> <span class="named-paragraph-number">9.1.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\treturn TRUE;\n"</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP9">&#167;9</a>.</li></ul><p class="inwebparagraph"><a id="SP9_1_1"></a><b>&#167;9.1.1. </b>In the absence of any <code class="display"><span class="extract-syntax">==&gt;</span></code> formulae, we simply set <code class="display"><span class="extract-syntax">*X</span></code> to the default
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP9">&#167;9</a>.</li></ul><p class="inwebparagraph"><a id="SP9_1_1"></a><b>&#167;9.1.1. </b>In the absence of any <span class="extract"><span class="extract-syntax">==&gt;</span></span> formulae, we simply set <span class="extract"><span class="extract-syntax">*X</span></span> to the default
result supplied; this is the production number within the grammar (0 for the
first line, 1 for the second, and so on) by default, with an undefined pointer.
</p>
@ -756,11 +756,11 @@ and that it produces an integer or a pointer according to what the
non-terminal expects as its main result. But we make one exception: if
the formula begins with a paragraph macro, then it can't be an expression,
and instead we read it as code in a void context. (This code will, we
assume, set <code class="display"><span class="extract-syntax">*X</span></code> and/or <code class="display"><span class="extract-syntax">*XP</span></code> in some ingenious way of its own.)
assume, set <span class="extract"><span class="extract-syntax">*X</span></span> and/or <span class="extract"><span class="extract-syntax">*XP</span></span> in some ingenious way of its own.)
</p>
<p class="inwebparagraph">Within the body of the formula, we allow a pseudo-macro to work: <code class="display"><span class="extract-syntax">WR[n]</span></code>
expands to word range <code class="display"><span class="extract-syntax">n</span></code> in the match which we're compositing. This actually
<p class="inwebparagraph">Within the body of the formula, we allow a pseudo-macro to work: <span class="extract"><span class="extract-syntax">WR[n]</span></span>
expands to word range <span class="extract"><span class="extract-syntax">n</span></span> in the match which we're compositing. This actually
expands like so:
</p>
@ -821,10 +821,10 @@ we also provide for some other special extensions to C.
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><a href="../foundation-module/4-sm.html#SP13" class="function-link"><span class="function-syntax">Str::get_at</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">original</span><span class="plain-syntax">, </span><span class="identifier-syntax">i</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10_1"></a><b>&#167;10.1. </b>For example, a function name like <code class="display"><span class="extract-syntax">Text::Parsing::get_next</span></code> must be rewritten
as <code class="display"><span class="extract-syntax">Text__Parsing__get_next</span></code> since colons aren't valid in C identifiers. The
</pre><p class="inwebparagraph"><a id="SP10_1"></a><b>&#167;10.1. </b>For example, a function name like <span class="extract"><span class="extract-syntax">Text::Parsing::get_next</span></span> must be rewritten
as <span class="extract"><span class="extract-syntax">Text__Parsing__get_next</span></span> since colons aren't valid in C identifiers. The
following is prone to all kinds of misreadings, of course; it picks up any use
of <code class="display"><span class="extract-syntax">::</span></code> between an alphanumberic character and a letter. In particular, code
of <span class="extract"><span class="extract-syntax">::</span></span> between an alphanumberic character and a letter. In particular, code
like
</p>
@ -854,9 +854,9 @@ Inform, where no misreadings occur.
<span class="plain-syntax"> </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP10">&#167;10</a>.</li></ul><p class="inwebparagraph"><a id="SP10_2"></a><b>&#167;10.2. </b>Angle brackets around a valid Preform variable name expand into its
C identifier; for example, <code class="display"><span class="extract-syntax">&lt;&lt;R&gt;&gt;</span></code> becomes <code class="display"><span class="extract-syntax">most_recent_result</span></code>.
We take no action if it's not a valid name, so <code class="display"><span class="extract-syntax">&lt;&lt;fish&gt;&gt;</span></code> becomes
just <code class="display"><span class="extract-syntax">&lt;&lt;fish&gt;&gt;</span></code>.
C identifier; for example, <span class="extract"><span class="extract-syntax">&lt;&lt;R&gt;&gt;</span></span> becomes <span class="extract"><span class="extract-syntax">most_recent_result</span></span>.
We take no action if it's not a valid name, so <span class="extract"><span class="extract-syntax">&lt;&lt;fish&gt;&gt;</span></span> becomes
just <span class="extract"><span class="extract-syntax">&lt;&lt;fish&gt;&gt;</span></span>.
</p>
@ -880,7 +880,7 @@ just <code class="display"><span class="extract-syntax">&lt;&lt;fish&gt;&gt;</sp
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">check_this</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP10">&#167;10</a>.</li></ul><p class="inwebparagraph"><a id="SP10_3"></a><b>&#167;10.3. </b>Similarly for nonterminals; <code class="display"><span class="extract-syntax">&lt;k-kind&gt;</span></code> might become <code class="display"><span class="extract-syntax">k_kind_NTM</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP10">&#167;10</a>.</li></ul><p class="inwebparagraph"><a id="SP10_3"></a><b>&#167;10.3. </b>Similarly for nonterminals; <span class="extract"><span class="extract-syntax">&lt;k-kind&gt;</span></span> might become <span class="extract"><span class="extract-syntax">k_kind_NTM</span></span>.
Here, though, there's a complication:
</p>
@ -894,8 +894,8 @@ Here, though, there's a complication:
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Text__Languages__parse_nt_against_word_range</span><span class="plain-syntax">(</span><span class="identifier-syntax">k_kind_NTM</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)) { ...</span>
</pre>
<p class="inwebparagraph">This is all syntactic sugar to make it easier to see parsing in action.
Anyway, it means we have to set <code class="display"><span class="extract-syntax">fcall_pos</span></code> to remember to add in the
two <code class="display"><span class="extract-syntax">NULL</span></code> arguments when we hit the <code class="display"><span class="extract-syntax">)</span></code> a little later. We're doing all
Anyway, it means we have to set <span class="extract"><span class="extract-syntax">fcall_pos</span></span> to remember to add in the
two <span class="extract"><span class="extract-syntax">NULL</span></span> arguments when we hit the <span class="extract"><span class="extract-syntax">)</span></span> a little later. We're doing all
of this fairly laxly, but as before: it only needs to work for Inform,
and Inform doesn't cause any trouble.
</p>
@ -947,7 +947,7 @@ the size of Inform 7, there's no significant gain from speeding them up
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">pnt</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>The special variables <code class="display"><span class="extract-syntax">&lt;&lt;R&gt;&gt;</span></code> and <code class="display"><span class="extract-syntax">&lt;&lt;RP&gt;&gt;</span></code> hold the results,
</pre><p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b>The special variables <span class="extract"><span class="extract-syntax">&lt;&lt;R&gt;&gt;</span></span> and <span class="extract"><span class="extract-syntax">&lt;&lt;RP&gt;&gt;</span></span> hold the results,
integer and pointer, for the most recent successful match. They're defined
in the Inform 7 web (see the code for parsing text against Preform grammars),
not by Inweb.
@ -971,7 +971,7 @@ Inweb.
</p>
<p class="inwebparagraph">So what does happen to it? The answer is that it's transcribed into an
auxiliary file called <code class="display"><span class="extract-syntax">Syntax.preform</span></code>, which Inform, once it is compiled,
auxiliary file called <span class="extract"><span class="extract-syntax">Syntax.preform</span></span>, which Inform, once it is compiled,
will read in at run-time. This is how that happens:
</p>
@ -1121,7 +1121,7 @@ nonterminal definitions:
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-is.html#SP14">&#167;14</a>.</li></ul><p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. Weaving methods. </b>If we're weaving just a document of Preform grammar, then we skip any lines
of C code which appear in <code class="display"><span class="extract-syntax">internal</span></code> nonterminal definitions:
of C code which appear in <span class="extract"><span class="extract-syntax">internal</span></span> nonterminal definitions:
</p>
<pre class="displayed-code all-displayed-code">
@ -1151,7 +1151,7 @@ of C code which appear in <code class="display"><span class="extract-syntax">int
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>In paragraphs where we spot Preform nonterminals being defined, we're
going to automatically apply the tag <code class="display"><span class="extract-syntax">^"Preform"</span></code>, but only if it already
going to automatically apply the tag <span class="extract"><span class="extract-syntax">^"Preform"</span></span>, but only if it already
exists. We watch for it here:
</p>

42
docs/inweb/4-lm.html
View file

@ -51,7 +51,7 @@ function togglePopup(material_id) {
independent of the programming language being written, woven or tangled;
Knuth began literate programming with Pascal, but now uses C, and the original
Pascal webs were mechanically translated into C ones with remarkably little
fuss or bother. Modern LP tools, such as <code class="display"><span class="extract-syntax">noweb</span></code>, aim to be language-agnostic.
fuss or bother. Modern LP tools, such as <span class="extract"><span class="extract-syntax">noweb</span></span>, aim to be language-agnostic.
But of course if you act the same on all languages, you give up the benefits
which might follow from knowing something about the languages you actually
write in.
@ -74,7 +74,7 @@ the web into chapters, sections and paragraphs, but for some languages we will
need a more detailed picture.
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">PARSE_TYPES_PAR_MTID</span></code> gives a language to look for type declarations.
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">PARSE_TYPES_PAR_MTID</span></span> gives a language to look for type declarations.
</p>
@ -86,7 +86,7 @@ need a more detailed picture.
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">LanguageMethods::parse_types</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>LanguageMethods::parse_types</b>:<br>The Parser - <a href="2-tp.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pl</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">PARSE_TYPES_PAR_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b><code class="display"><span class="extract-syntax">PARSE_FUNCTIONS_PAR_MTID</span></code> is, similarly, for function declarations.
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b><span class="extract"><span class="extract-syntax">PARSE_FUNCTIONS_PAR_MTID</span></span> is, similarly, for function declarations.
</p>
@ -98,7 +98,7 @@ need a more detailed picture.
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">LanguageMethods::parse_functions</span><button class="popup" onclick="togglePopup('usagePopup2')">...<span class="popuptext" id="usagePopup2">Usage of <b>LanguageMethods::parse_functions</b>:<br>The Parser - <a href="2-tp.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pl</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">PARSE_FUNCTIONS_PAR_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b><code class="display"><span class="extract-syntax">FURTHER_PARSING_PAR_MTID</span></code> is "further" in that it is called when the main
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b><span class="extract"><span class="extract-syntax">FURTHER_PARSING_PAR_MTID</span></span> is "further" in that it is called when the main
parser has finished work; it typically looks over the whole web for something
of interest.
</p>
@ -112,7 +112,7 @@ of interest.
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">LanguageMethods::further_parsing</span><button class="popup" onclick="togglePopup('usagePopup3')">...<span class="popuptext" id="usagePopup3">Usage of <b>LanguageMethods::further_parsing</b>:<br>The Parser - <a href="2-tp.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pl</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">FURTHER_PARSING_PAR_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b><code class="display"><span class="extract-syntax">SUBCATEGORISE_LINE_PAR_MTID</span></code> looks at a single line, after the main parser
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b><span class="extract"><span class="extract-syntax">SUBCATEGORISE_LINE_PAR_MTID</span></span> looks at a single line, after the main parser
has given it a category. The idea is not so much to second-guess the parser
(although we can) but to change to a more exotic category which it would
otherwise never produce.
@ -128,7 +128,7 @@ otherwise never produce.
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">SUBCATEGORISE_LINE_PAR_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Comments have different syntax in different languages. The method here is
expected to look for a comment on the <code class="display"><span class="extract-syntax">line</span></code>, and if so to return <code class="display"><span class="extract-syntax">TRUE</span></code>,
expected to look for a comment on the <span class="extract"><span class="extract-syntax">line</span></span>, and if so to return <span class="extract"><span class="extract-syntax">TRUE</span></span>,
but not before splicing the non-comment parts of the line before and
within the comment into the supplied strings.
</p>
@ -151,8 +151,8 @@ the top to the bottom of the file.
</p>
<p class="inwebparagraph">The top of the tangled file is a header called the "shebang". By default,
there's nothing there, but <code class="display"><span class="extract-syntax">SHEBANG_TAN_MTID</span></code> allows the language to add one.
For example, Perl prints <code class="display"><span class="extract-syntax">#!/usr/bin/perl</span></code> here.
there's nothing there, but <span class="extract"><span class="extract-syntax">SHEBANG_TAN_MTID</span></span> allows the language to add one.
For example, Perl prints <span class="extract"><span class="extract-syntax">#!/usr/bin/perl</span></span> here.
</p>
@ -194,10 +194,10 @@ at tangled (therefore not original) material.
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">ADDITIONAL_EARLY_MATTER_TAN_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">target</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>A tangled file then normally declares "definitions". The following write a
definition of the constant named <code class="display"><span class="extract-syntax">term</span></code> as the value given. If the value spans
multiple lines, the first-line part is supplied to <code class="display"><span class="extract-syntax">START_DEFN_TAN_MTID</span></code> and
then subsequent lines are fed in order to <code class="display"><span class="extract-syntax">PROLONG_DEFN_TAN_MTID</span></code>. At the end,
<code class="display"><span class="extract-syntax">END_DEFN_TAN_MTID</span></code> is called.
definition of the constant named <span class="extract"><span class="extract-syntax">term</span></span> as the value given. If the value spans
multiple lines, the first-line part is supplied to <span class="extract"><span class="extract-syntax">START_DEFN_TAN_MTID</span></span> and
then subsequent lines are fed in order to <span class="extract"><span class="extract-syntax">PROLONG_DEFN_TAN_MTID</span></span>. At the end,
<span class="extract"><span class="extract-syntax">END_DEFN_TAN_MTID</span></span> is called.
</p>
@ -264,8 +264,8 @@ the more routine matter, tangling ordinary paragraphs into code.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> (</span><span class="identifier-syntax">rv</span><span class="plain-syntax">)?</span><span class="identifier-syntax">FALSE:TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. </b>Inweb supports very few "tangle commands", that is, instructions written
inside double squares <code class="display"><span class="extract-syntax">[[Thus]]</span></code>. These can be handled by attaching methods
as follows, which return <code class="display"><span class="extract-syntax">TRUE</span></code> if they recognised and acted on the command.
inside double squares <span class="extract"><span class="extract-syntax">[[Thus]]</span></span>. These can be handled by attaching methods
as follows, which return <span class="extract"><span class="extract-syntax">TRUE</span></span> if they recognised and acted on the command.
</p>
@ -281,7 +281,7 @@ as follows, which return <code class="display"><span class="extract-syntax">TRUE
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. </b>The following methods make it possible for languages to tangle unorthodox
lines into code. Ordinarily, only <code class="display"><span class="extract-syntax">CODE_BODY_LCAT</span></code> lines are tangled, but
lines into code. Ordinarily, only <span class="extract"><span class="extract-syntax">CODE_BODY_LCAT</span></span> lines are tangled, but
we can intervene to say that we want to tangle a different line; and if we
do so, we should then act on that basis.
</p>
@ -304,7 +304,7 @@ do so, we should then act on that basis.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. </b>In order for C compilers to report C syntax errors on the correct line,
despite rearranging by automatic tools, C conventionally recognises the
preprocessor directive <code class="display"><span class="extract-syntax">#line</span></code> to tell it that a contiguous extract follows
preprocessor directive <span class="extract"><span class="extract-syntax">#line</span></span> to tell it that a contiguous extract follows
from the given file; we generate this automatically.
</p>
@ -319,7 +319,7 @@ from the given file; we generate this automatically.
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP16"></a><b>&#167;16. </b>The following hooks are provided so that we can top and/or tail the expansion
of paragraph macros in the code. For example, C-like languages, use this to
splice <code class="display"><span class="extract-syntax">{</span></code> and <code class="display"><span class="extract-syntax">}</span></code> around the expanded matter.
splice <span class="extract"><span class="extract-syntax">{</span></span> and <span class="extract"><span class="extract-syntax">}</span></span> around the expanded matter.
</p>
@ -338,7 +338,7 @@ splice <code class="display"><span class="extract-syntax">{</span></code> and <c
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>It's a sad necessity, but sometimes we have to unconditionally tangle code
for a preprocessor to conditionally read: that is, to tangle code which contains
<code class="display"><span class="extract-syntax">#ifdef</span></code> or similar preprocessor directive.
<span class="extract"><span class="extract-syntax">#ifdef</span></span> or similar preprocessor directive.
</p>
@ -369,7 +369,7 @@ for a preprocessor to conditionally read: that is, to tangle code which contains
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP19"></a><b>&#167;19. </b>The inner code tangler now acts on all code known not to contain CWEB
macros or double-square substitutions. In almost every language this simply
passes the code straight through, printing <code class="display"><span class="extract-syntax">original</span></code> to <code class="display"><span class="extract-syntax">OUT</span></code>.
passes the code straight through, printing <span class="extract"><span class="extract-syntax">original</span></span> to <span class="extract"><span class="extract-syntax">OUT</span></span>.
</p>
@ -474,7 +474,7 @@ sake, which minimises the knock-on effect of any colouring mistakes.
<span class="plain-syntax"> </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">colouring</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP26"></a><b>&#167;26. </b>This method is called for each code line to be woven. If it returns <code class="display"><span class="extract-syntax">FALSE</span></code>, the
</pre><p class="inwebparagraph"><a id="SP26"></a><b>&#167;26. </b>This method is called for each code line to be woven. If it returns <span class="extract"><span class="extract-syntax">FALSE</span></span>, the
weaver carries on in the normal way. If not, it does nothing, assuming that the
method has already woven something more attractive.
</p>
@ -492,7 +492,7 @@ method has already woven something more attractive.
<span class="plain-syntax"> </span><span class="identifier-syntax">IMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">rv</span><span class="plain-syntax">, </span><span class="identifier-syntax">pl</span><span class="plain-syntax">, </span><span class="constant-syntax">WEAVE_CODE_LINE_WEA_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">concluding_comment</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. </b>When Inweb creates a new <code class="display"><span class="extract-syntax"> </span></code>, it lets everybody know about that.
</pre><p class="inwebparagraph"><a id="SP27"></a><b>&#167;27. </b>When Inweb creates a new <span class="extract"><span class="extract-syntax"> </span></span>, it lets everybody know about that.
</p>

60
docs/inweb/4-pl.html
View file

@ -47,7 +47,7 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="4-pl.html#SP1">&#167;1. Languages</a></li><li><a href="4-pl.html#SP9">&#167;9. Blocks</a></li><li><a href="4-pl.html#SP11">&#167;11. Colouring Rules</a></li><li><a href="4-pl.html#SP14">&#167;14. Reserved words</a></li><li><a href="4-pl.html#SP15">&#167;15. Expressions</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Languages. </b>Programming languages are identified by name: for example, <code class="display"><span class="extract-syntax">C++</span></code> or <code class="display"><span class="extract-syntax">Perl</span></code>.
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Languages. </b>Programming languages are identified by name: for example, <span class="extract"><span class="extract-syntax">C++</span></span> or <span class="extract"><span class="extract-syntax">Perl</span></span>.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b></p>
@ -191,16 +191,16 @@ into the following structure (one per language):
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">suppress_disclaimer</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">C_like</span><span class="plain-syntax">; </span><span class="comment"> languages with this set have access to extra features</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">reserved_words</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">reserved_word</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">reserved_words</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">reserved_word</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hash_table</span><span class="plain-syntax"> </span><span class="identifier-syntax">built_in_keywords</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_language_block</span><span class="plain-syntax"> *</span><span class="identifier-syntax">program</span><span class="plain-syntax">; </span><span class="comment"> algorithm for syntax colouring</span>
<span class="plain-syntax"> </span><span class="constant-syntax">METHOD_CALLS</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">programming_language</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure programming_language is accessed in 1/pc, 3/tt, 4/taf, 4/lm, 4/as, 4/tp, 5/hf, 5/df and here.</li></ul><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>This is a simple one-pass compiler. The <code class="display"><span class="extract-syntax">language_reader_state</span></code> provides
</pre><ul class="endnotetexts"><li>The structure programming_language is accessed in 1/pc, 3/tt, 4/taf, 4/lm, 4/as, 4/tp, 5/hf, 5/df and here.</li></ul><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>This is a simple one-pass compiler. The <span class="extract"><span class="extract-syntax">language_reader_state</span></span> provides
the only state preserved as we work through line by line, except of course
that we are also working on the programming language it is <code class="display"><span class="extract-syntax">defining</span></code>. The
<code class="display"><span class="extract-syntax">current_block</span></code> is the braced block of colouring instructions we are
that we are also working on the programming language it is <span class="extract"><span class="extract-syntax">defining</span></span>. The
<span class="extract"><span class="extract-syntax">current_block</span></span> is the braced block of colouring instructions we are
currently inside.
</p>
@ -267,7 +267,7 @@ the language whose name is InC gets even more, without having to ask.
</p>
<p class="inwebparagraph">Languages have effect through their method calls, which is how those
extra features are provided. The call to <code class="display"><span class="extract-syntax">ACMESupport::add_fallbacks</span></code>
extra features are provided. The call to <span class="extract"><span class="extract-syntax">ACMESupport::add_fallbacks</span></span>
adds generic method calls to give effect to the settings in the definition.
</p>
@ -449,7 +449,7 @@ runs of a given colour, or give an if-X-then-Y rule:
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"line in colouring block illegible"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-pl.html#SP8">&#167;8</a>.</li></ul><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Blocks. </b>These are code blocks of colouring instructions. A block whose <code class="display"><span class="extract-syntax">parent</span></code> is <code class="display"><span class="extract-syntax">NULL</span></code>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-pl.html#SP8">&#167;8</a>.</li></ul><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Blocks. </b>These are code blocks of colouring instructions. A block whose <span class="extract"><span class="extract-syntax">parent</span></span> is <span class="extract"><span class="extract-syntax">NULL</span></span>
represents a complete program.
</p>
@ -464,12 +464,12 @@ represents a complete program.
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_language_block</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rules</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">colouring_rule</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_language_block</span><span class="plain-syntax"> *</span><span class="identifier-syntax">parent</span><span class="plain-syntax">; </span><span class="comment"> or </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment"> for the topmost one</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">run</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><code class="display"><span class="extract-syntax">*_CRULE_RUN</span></code><span class="comment"> values, or else a colour</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">run_instance</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">INSTANCES_CRULE_RUN</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">char_set</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><code class="display"><span class="extract-syntax">CHARACTERS_IN_CRULE_RUN</span></code>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_regexp_text</span><span class="plain-syntax">[</span><span class="constant-syntax">MAX_ILDF_REGEXP_LENGTH</span><span class="plain-syntax">]; </span><span class="comment"> used for </span><code class="display"><span class="extract-syntax">MATCHES_CRULE_RUN</span></code><span class="comment">, </span><code class="display"><span class="extract-syntax">BRACKETS_CRULE_RUN</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rules</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">colouring_rule</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_language_block</span><span class="plain-syntax"> *</span><span class="identifier-syntax">parent</span><span class="plain-syntax">; </span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment"> for the topmost one</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">run</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><span class="extract"><span class="extract-syntax">*_CRULE_RUN</span></span><span class="comment"> values, or else a colour</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">run_instance</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">INSTANCES_CRULE_RUN</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">char_set</span><span class="plain-syntax">; </span><span class="comment"> used only for </span><span class="extract"><span class="extract-syntax">CHARACTERS_IN_CRULE_RUN</span></span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_regexp_text</span><span class="plain-syntax">[</span><span class="constant-syntax">MAX_ILDF_REGEXP_LENGTH</span><span class="plain-syntax">]; </span><span class="comment"> used for </span><span class="extract"><span class="extract-syntax">MATCHES_CRULE_RUN</span></span><span class="comment">, </span><span class="extract"><span class="extract-syntax">BRACKETS_CRULE_RUN</span></span>
<span class="plain-syntax"> </span><span class="comment"> workspace during painting</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax">; </span><span class="comment"> of a regular expression</span>
@ -500,28 +500,28 @@ little context before it (where available).
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">NOT_A_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> </span><span class="comment"> this isn't a prefix rule</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">prefix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">spaced prefix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">optionally spaced prefix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">suffix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">spaced suffix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">7</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">optionally spaced suffix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">prefix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">spaced prefix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">optionally spaced prefix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">suffix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">spaced suffix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">7</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">optionally spaced suffix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">MAX_ILDF_REGEXP_LENGTH</span><span class="plain-syntax"> </span><span class="constant-syntax">64</span>
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_rule</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="comment"> the premiss:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sense</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">FALSE</span></code><span class="comment"> to negate the condition</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_colour</span><span class="plain-syntax">; </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">coloured C</span></code><span class="comment">, or else </span><code class="display"><span class="extract-syntax">NOT_A_COLOUR</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_keyword_of_colour</span><span class="plain-syntax">; </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">keyword C</span></code><span class="comment">, or else </span><code class="display"><span class="extract-syntax">NOT_A_COLOUR</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sense</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">FALSE</span></span><span class="comment"> to negate the condition</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_colour</span><span class="plain-syntax">; </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">coloured C</span></span><span class="comment">, or else </span><span class="extract"><span class="extract-syntax">NOT_A_COLOUR</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_keyword_of_colour</span><span class="plain-syntax">; </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">keyword C</span></span><span class="comment">, or else </span><span class="extract"><span class="extract-syntax">NOT_A_COLOUR</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">match_text</span><span class="plain-syntax">; </span><span class="comment"> or length 0 to mean "anything"</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_prefix</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><code class="display"><span class="extract-syntax">*_RULE_PREFIX</span></code><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_prefix</span><span class="plain-syntax">; </span><span class="comment"> one of the </span><span class="extract"><span class="extract-syntax">*_RULE_PREFIX</span></span><span class="comment"> values above</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">match_regexp_text</span><span class="plain-syntax">[</span><span class="constant-syntax">MAX_ILDF_REGEXP_LENGTH</span><span class="plain-syntax">];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax">; </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">number N</span></code><span class="comment"> rules; 0 for others</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">number_of</span><span class="plain-syntax">; </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">number N of M</span></code><span class="comment"> rules; 0 for others</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax">; </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">number N</span></span><span class="comment"> rules; 0 for others</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">number_of</span><span class="plain-syntax">; </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">number N of M</span></span><span class="comment"> rules; 0 for others</span>
<span class="plain-syntax"> </span><span class="comment"> the conclusion:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_language_block</span><span class="plain-syntax"> *</span><span class="identifier-syntax">execute_block</span><span class="plain-syntax">; </span><span class="comment"> or </span><code class="display"><span class="extract-syntax">NULL</span></code><span class="comment">, in which case...</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colouring_language_block</span><span class="plain-syntax"> *</span><span class="identifier-syntax">execute_block</span><span class="plain-syntax">; </span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">NULL</span></span><span class="comment">, in which case...</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">set_to_colour</span><span class="plain-syntax">; </span><span class="comment"> ...paint the snippet in this colour</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">set_prefix_to_colour</span><span class="plain-syntax">; </span><span class="comment"> ...also paint this (same for suffix)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">debug</span><span class="plain-syntax">; </span><span class="comment"> ...or print debugging text to console</span>
@ -634,7 +634,7 @@ little context before it (where available).
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"action after '=&gt;' illegible"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-pl.html#SP13">&#167;13</a>.</li></ul><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Reserved words. </b>Note that these can come in any colour, though usually it's <code class="display"><span class="extract-syntax">!reserved</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-pl.html#SP13">&#167;13</a>.</li></ul><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Reserved words. </b>Note that these can come in any colour, though usually it's <span class="extract"><span class="extract-syntax">!reserved</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -702,7 +702,7 @@ but which are not expressible in the syntax of this file.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">PLAIN_COLOUR</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP16"></a><b>&#167;16. </b>A boolean must be written as <code class="display"><span class="extract-syntax">true</span></code> or <code class="display"><span class="extract-syntax">false</span></code>.
</pre><p class="inwebparagraph"><a id="SP16"></a><b>&#167;16. </b>A boolean must be written as <span class="extract"><span class="extract-syntax">true</span></span> or <span class="extract"><span class="extract-syntax">false</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -714,8 +714,8 @@ but which are not expressible in the syntax of this file.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>In text, <code class="display"><span class="extract-syntax">\n</span></code> represents a newline, <code class="display"><span class="extract-syntax">\s</span></code> a space and <code class="display"><span class="extract-syntax">\t</span></code> a tab. Spaces
can be given in the ordinary way inside a text in any case. <code class="display"><span class="extract-syntax">\\</span></code> is a
</pre><p class="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>In text, <span class="extract"><span class="extract-syntax">\n</span></span> represents a newline, <span class="extract"><span class="extract-syntax">\s</span></span> a space and <span class="extract"><span class="extract-syntax">\t</span></span> a tab. Spaces
can be given in the ordinary way inside a text in any case. <span class="extract"><span class="extract-syntax">\\</span></span> is a
literal backslash.
</p>

24
docs/inweb/4-taf.html
View file

@ -47,17 +47,17 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="4-taf.html#SP6">&#167;6. Functions</a></li><li><a href="4-taf.html#SP8">&#167;8. Cataloguing</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>For each <code class="display"><span class="extract-syntax">typedef struct</span></code> we find, we will make one of these:
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>For each <span class="extract"><span class="extract-syntax">typedef struct</span></span> we find, we will make one of these:
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">language_type</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">structure_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">tangled</span><span class="plain-syntax">; </span><span class="comment"> whether the structure definition has been tangled out</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">structure_header_at</span><span class="plain-syntax">; </span><span class="comment"> opening line of </span><code class="display"><span class="extract-syntax">typedef</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">typedef_ends</span><span class="plain-syntax">; </span><span class="comment"> closing line, where </span><code class="display"><span class="extract-syntax">}</span></code><span class="comment"> appears</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">incorporates</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">language_type</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">elements</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">structure_element</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">structure_header_at</span><span class="plain-syntax">; </span><span class="comment"> opening line of </span><span class="extract"><span class="extract-syntax">typedef</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">typedef_ends</span><span class="plain-syntax">; </span><span class="comment"> closing line, where </span><span class="extract"><span class="extract-syntax">}</span></span><span class="comment"> appears</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">incorporates</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">language_type</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">elements</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">structure_element</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">language_type</span><span class="plain-syntax"> *</span><span class="identifier-syntax">next_cst_alphabetically</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">language_type</span><span class="plain-syntax">;</span>
@ -120,13 +120,13 @@ function togglePopup(material_id) {
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">placed</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) </span><span class="identifier-syntax">last</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next_cst_alphabetically</span><span class="plain-syntax"> = </span><span class="identifier-syntax">str</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-taf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>A language can also create an instance of <code class="display"><span class="extract-syntax">structure_element</span></code> to record the
existence of the element <code class="display"><span class="extract-syntax">val</span></code>, and add it to the linked list of elements of
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-taf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>A language can also create an instance of <span class="extract"><span class="extract-syntax">structure_element</span></span> to record the
existence of the element <span class="extract"><span class="extract-syntax">val</span></span>, and add it to the linked list of elements of
the structure being defined.
</p>
<p class="inwebparagraph">In InC, only, certain element names used often in Inform's source code are
given mildly special treatment. This doesn't amount to much. <code class="display"><span class="extract-syntax">allow_sharing</span></code>
given mildly special treatment. This doesn't amount to much. <span class="extract"><span class="extract-syntax">allow_sharing</span></span>
has no effect on tangling, so it doesn't change the program. It simply
affects the reports in the woven code about where structures are used.
</p>
@ -168,9 +168,9 @@ affects the reports in the woven code about where structures are used.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">language_function</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"cultivate"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_type</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"tree *"</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_arguments</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><code class="display"><span class="extract-syntax">"int rainfall)"</span></code><span class="comment">: note </span><code class="display"><span class="extract-syntax">)</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_name</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"cultivate"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_type</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"tree *"</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_arguments</span><span class="plain-syntax">; </span><span class="comment"> e.g., </span><span class="extract"><span class="extract-syntax">"int rainfall)"</span></span><span class="comment">: note </span><span class="extract"><span class="extract-syntax">)</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">source_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_header_at</span><span class="plain-syntax">; </span><span class="comment"> where the first line of the header begins</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">within_namespace</span><span class="plain-syntax">; </span><span class="comment"> written using InC namespace dividers</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">called_from_other_sections</span><span class="plain-syntax">;</span>
@ -254,7 +254,7 @@ part of the function structure. We'll need it when predeclaring the function.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">err_mess</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-taf.html#SP7">&#167;7</a>.</li></ul><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Cataloguing. </b>This implements the additional information in the <code class="display"><span class="extract-syntax">-structures</span></code> and <code class="display"><span class="extract-syntax">-functions</span></code>
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-taf.html#SP7">&#167;7</a>.</li></ul><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Cataloguing. </b>This implements the additional information in the <span class="extract"><span class="extract-syntax">-structures</span></span> and <span class="extract"><span class="extract-syntax">-functions</span></span>
forms of section catalogue.
</p>

26
docs/inweb/4-tp.html
View file

@ -48,15 +48,15 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="4-tp.html#SP7">&#167;7. Painting a file</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This is a very simple syntax colouring algorithm. The work is done by the
function <code class="display"><span class="extract-syntax">Painter::syntax_colour</span></code>, which can in principle be applied to texts
function <span class="extract"><span class="extract-syntax">Painter::syntax_colour</span></span>, which can in principle be applied to texts
of any length. But it's usually convenient to run it on a long file one line
at a time, so that it is called repeatedly. The variable <code class="display"><span class="extract-syntax">colouring_state</span></code>
at a time, so that it is called repeatedly. The variable <span class="extract"><span class="extract-syntax">colouring_state</span></span>
remembers where we were at the end of the previous line, so that we can pick
up again later at the start of the next.
</p>
<p class="inwebparagraph">Because of that, we need to call the following before we begin a run of calls
to <code class="display"><span class="extract-syntax">Painter::syntax_colour</span></code>:
to <span class="extract"><span class="extract-syntax">Painter::syntax_colour</span></span>:
</p>
<pre class="displayed-code all-displayed-code">
@ -65,16 +65,16 @@ to <code class="display"><span class="extract-syntax">Painter::syntax_colour</sp
<span class="plain-syntax"> </span><span class="identifier-syntax">colouring_state</span><span class="plain-syntax"> = </span><span class="constant-syntax">PLAIN_COLOUR</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">painter_count</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>As we begin, the text to colour is in <code class="display"><span class="extract-syntax">matter</span></code>, while <code class="display"><span class="extract-syntax">colouring</span></code> is an
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>As we begin, the text to colour is in <span class="extract"><span class="extract-syntax">matter</span></span>, while <span class="extract"><span class="extract-syntax">colouring</span></span> is an
equal-length text where each character represents the colour of its
corresponding character in <code class="display"><span class="extract-syntax">matter</span></code>. For example, we might start as:
corresponding character in <span class="extract"><span class="extract-syntax">matter</span></span>. For example, we might start as:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> int x = 55;</span>
<span class="plain-syntax"> ppppppppppp</span>
</pre>
<p class="inwebparagraph">with every character having <code class="display"><span class="extract-syntax">PLAIN_COLOUR</span></code>, but end up with:
<p class="inwebparagraph">with every character having <span class="extract"><span class="extract-syntax">PLAIN_COLOUR</span></span>, but end up with:
</p>
<pre class="displayed-code all-displayed-code">
@ -220,7 +220,7 @@ its colouring program.
</pre><ul class="endnotetexts"><li>This code is used in <a href="4-tp.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_3"></a><b>&#167;2.3. </b>For the moment, we always adopt the C rules on identifiers: they have to
begin with an underscore or letter, then continue with underscores or
alphanumeric characters, except that if the language allows it then they
can contain a <code class="display"><span class="extract-syntax">::</span></code> namespace divider.
can contain a <span class="extract"><span class="extract-syntax">::</span></span> namespace divider.
</p>
<pre class="displayed-code all-displayed-code">
@ -353,12 +353,12 @@ rule across the whole snippet before moving on to the next.
<pre class="definitions">
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">prefix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">spaced prefix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">optionally spaced prefix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">suffix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">spaced suffix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">7</span><span class="plain-syntax"> </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">optionally spaced suffix P</span></code>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">prefix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">spaced prefix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_PREFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">optionally spaced prefix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">UNSPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">suffix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">spaced suffix P</span></span>
<span class="definition-keyword">define</span> <span class="constant-syntax">OPTIONALLY_SPACED_RULE_SUFFIX</span><span class="plain-syntax"> </span><span class="constant-syntax">7</span><span class="plain-syntax"> </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">optionally spaced suffix P</span></span>
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Painter::satisfies</span><button class="popup" onclick="togglePopup('usagePopup7')">...<span class="popuptext" id="usagePopup7">Usage of <b>Painter::satisfies</b>:<br><a href="4-tp.html#SP4">&#167;4</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">hash_table</span><span class="plain-syntax"> *</span><span class="identifier-syntax">HT</span><span class="plain-syntax">, </span><span class="reserved-syntax">colouring_rule</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rule</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">matter</span><span class="plain-syntax">,</span>

2
docs/inweb/5-df.html
View file

@ -122,7 +122,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure debugging_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/ptf, 5/tf, 5/hf, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b><code class="display">
</pre><ul class="endnotetexts"><li>The structure debugging_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/ptf, 5/tf, 5/hf, 5/wp, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Render document</span> <span class="named-paragraph-number">2.1</span>&gt; =
</code></p>

16
docs/inweb/5-fm.html
View file

@ -67,7 +67,7 @@ through optional method calls.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">wf</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">weave_format</span><span class="plain-syntax"> *</span><span class="function-syntax">Formats::find_by_name</span><button class="popup" onclick="togglePopup('usagePopup2')">...<span class="popuptext" id="usagePopup2">Usage of <b>Formats::find_by_name</b>:<br><a href="5-fm.html#SP10">&#167;10</a>, Patterns - <a href="1-ptt.html#SP3_2">&#167;3.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">weave_format</span><span class="plain-syntax"> *</span><span class="function-syntax">Formats::find_by_name</span><button class="popup" onclick="togglePopup('usagePopup2')">...<span class="popuptext" id="usagePopup2">Usage of <b>Formats::find_by_name</b>:<br><a href="5-fm.html#SP10">&#167;10</a>, Patterns - <a href="1-ptt.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_format</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wf</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">wf</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_format</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><span class="identifier-syntax">wf</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">format_name</span><span class="plain-syntax">))</span>
@ -76,8 +76,8 @@ through optional method calls.
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure weave_format is accessed in 1/ts, 5/wp and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Note that this is the file extension before any post-processing. For
example, PDFs are made by weaving a TeX file and then running this through
<code class="display"><span class="extract-syntax">pdftex</span></code>. The extension here will be <code class="display"><span class="extract-syntax">.tex</span></code> because that's what the weave
stage produces, even though we will later end up with a <code class="display"><span class="extract-syntax">.pdf</span></code>.
<span class="extract"><span class="extract-syntax">pdftex</span></span>. The extension here will be <span class="extract"><span class="extract-syntax">.tex</span></span> because that's what the weave
stage produces, even though we will later end up with a <span class="extract"><span class="extract-syntax">.pdf</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -98,13 +98,13 @@ stage produces, even though we will later end up with a <code class="display"><s
putting away that needs tp be done.
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">BEGIN_WEAVING_FOR_MTID</span></code> is called before any output is generated, indeed,
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">BEGIN_WEAVING_FOR_MTID</span></span> is called before any output is generated, indeed,
before even the filename(s) for the output are worked out. Note that it
can return a <code class="display"><span class="extract-syntax">*_SWM</span></code> code to change the swarm behaviour of the weave to come;
can return a <span class="extract"><span class="extract-syntax">*_SWM</span></span> code to change the swarm behaviour of the weave to come;
this is helpful for EPUB weaving.
</p>
<p class="inwebparagraph">More simply, <code class="display"><span class="extract-syntax">END_WEAVING_FOR_MTID</span></code> is called when all weaving is done.
<p class="inwebparagraph">More simply, <span class="extract"><span class="extract-syntax">END_WEAVING_FOR_MTID</span></span> is called when all weaving is done.
</p>
@ -124,7 +124,7 @@ this is helpful for EPUB weaving.
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Formats::end_weaving</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>Formats::end_weaving</b>:<br>Program Control - <a href="1-pc.html#SP7_4_3">&#167;7.4.3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">VMETHOD_CALL</span><span class="plain-syntax">(</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax">, </span><span class="constant-syntax">END_WEAVING_FOR_MTID</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b><code class="display"><span class="extract-syntax">RENDER_FOR_MTID</span></code> renders the weave tree in the given format: a format must
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b><span class="extract"><span class="extract-syntax">RENDER_FOR_MTID</span></span> renders the weave tree in the given format: a format must
provide this.
</p>
@ -225,7 +225,7 @@ to make an index page in HTML which provides annotated links to those PDFs.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>And in that index file, we may want to substitute in values for placeholder
text like <code class="display"><span class="extract-syntax">[[PDF Size]]</span></code> in the template file. This is the <code class="display"><span class="extract-syntax">detail</span></code>.
text like <span class="extract"><span class="extract-syntax">[[PDF Size]]</span></span> in the template file. This is the <span class="extract"><span class="extract-syntax">detail</span></span>.
</p>

29
docs/inweb/5-hf.html
View file

@ -85,7 +85,7 @@ but in fact that's fine here.)
</pre>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">html_in_para</span><span class="plain-syntax"> = </span><span class="constant-syntax">HTML_OUT</span><span class="plain-syntax">; </span><span class="comment"> one of the above</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">item_depth</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment"> for </span><code class="display"><span class="extract-syntax">HTML_IN_LI</span></code><span class="comment"> only: how many lists we're nested inside</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">item_depth</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment"> for </span><span class="extract"><span class="extract-syntax">HTML_IN_LI</span></span><span class="comment"> only: how many lists we're nested inside</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFormat::p</span><button class="popup" onclick="togglePopup('usagePopup2')">...<span class="popuptext" id="usagePopup2">Usage of <b>HTMLFormat::p</b>:<br><a href="5-hf.html#SP5_9">&#167;5.9</a>, <a href="5-hf.html#SP5_12">&#167;5.12</a>, <a href="5-hf.html#SP5_15">&#167;5.15</a>, <a href="5-hf.html#SP5_29">&#167;5.29</a>, <a href="5-hf.html#SP6">&#167;6</a>, <a href="5-hf.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">class</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">class</span><span class="plain-syntax">) </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">, </span><span class="string-syntax">"class=\"%s\""</span><span class="plain-syntax">, </span><span class="identifier-syntax">class</span><span class="plain-syntax">)</span>
@ -246,7 +246,7 @@ which is itself inside a list entry"; and so on.
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"unable to render unknown node"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure HTML_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/ptf, 5/tf, 5/df, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b><code class="display">
</pre><ul class="endnotetexts"><li>The structure HTML_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/ptf, 5/tf, 5/df, 5/wp, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Render head</span> <span class="named-paragraph-number">5.1</span>&gt; =
</code></p>
@ -365,7 +365,7 @@ which is itself inside a list entry"; and so on.
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">RF</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP3" class="function-link"><span class="function-syntax">Filenames::from_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">figname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN</span><span class="plain-syntax">(</span><span class="string-syntax">"center"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/5-htm.html#SP14" class="function-link"><span class="function-syntax">HTML::image_to_dimensions</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">RF</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">w</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">h</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"center"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-hf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_12"></a><b>&#167;5.12. </b><code class="display">
@ -448,8 +448,8 @@ which is itself inside a list entry"; and so on.
<span class="plain-syntax"> </span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_material_seen</span><span class="plain-syntax"> = </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">material_type</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-hf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_13"></a><b>&#167;5.13. </b>This has to embed some Internet-sourced content. <code class="display"><span class="extract-syntax">service</span></code>
here is something like <code class="display"><span class="extract-syntax">YouTube</span></code> or <code class="display"><span class="extract-syntax">Soundcloud</span></code>, and <code class="display"><span class="extract-syntax">ID</span></code> is whatever code
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-hf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_13"></a><b>&#167;5.13. </b>This has to embed some Internet-sourced content. <span class="extract"><span class="extract-syntax">service</span></span>
here is something like <span class="extract"><span class="extract-syntax">YouTube</span></span> or <span class="extract"><span class="extract-syntax">Soundcloud</span></span>, and <span class="extract"><span class="extract-syntax">ID</span></span> is whatever code
that service uses to identify the video/audio in question.
</p>
@ -659,9 +659,8 @@ that service uses to identify the video/audio in question.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_footnote_cue_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_weave_footnote_cue_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::get_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Footnotes Plugin"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::ne_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"None"</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">footnotes_plugin</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="1-ts.html#SP3" class="function-link"><span class="function-syntax">Swarm::ensure_plugin</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;sup id=\"fnref:%S\"&gt;&lt;a href=\"#fn:%S\" rel=\"footnote\"&gt;%S&lt;/a&gt;&lt;/sup&gt;"</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">cue_text</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">cue_text</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">cue_text</span><span class="plain-syntax">);</span>
@ -671,9 +670,8 @@ that service uses to identify the video/audio in question.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_begin_footnote_text_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_weave_begin_footnote_text_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::get_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Footnotes Plugin"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::ne_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"None"</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">footnotes_plugin</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="1-ts.html#SP3" class="function-link"><span class="function-syntax">Swarm::ensure_plugin</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn_plugin_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;li class=\"footnote\" id=\"fn:%S\"&gt;&lt;p class=\"inwebfootnote\"&gt;"</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">cue_text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">M</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">child</span><span class="plain-syntax">; </span><span class="identifier-syntax">M</span><span class="plain-syntax">; </span><span class="identifier-syntax">M</span><span class="plain-syntax"> = </span><span class="identifier-syntax">M</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next</span><span class="plain-syntax">)</span>
@ -733,10 +731,10 @@ that service uses to identify the video/audio in question.
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"code"</span><span class="plain-syntax">, </span><span class="string-syntax">"class=\"display\""</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"span"</span><span class="plain-syntax">, </span><span class="string-syntax">"class=\"extract\""</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">M</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">child</span><span class="plain-syntax">; </span><span class="identifier-syntax">M</span><span class="plain-syntax">; </span><span class="identifier-syntax">M</span><span class="plain-syntax"> = </span><span class="identifier-syntax">M</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP13" class="function-link"><span class="function-syntax">Trees::traverse_from</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">M</span><span class="plain-syntax">, &amp;</span><a href="5-hf.html#SP5" class="function-link"><span class="function-syntax">HTMLFormat::render_visit</span></a><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">hrs</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">+1);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"code"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"span"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-hf.html#SP5">&#167;5</a>.</li></ul><p class="inwebparagraph"><a id="SP5_34"></a><b>&#167;5.34. </b><code class="display">
&lt;<span class="named-paragraph-defn">Render locale</span> <span class="named-paragraph-number">5.34</span>&gt; =
@ -759,9 +757,8 @@ that service uses to identify the video/audio in question.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_maths_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_weave_maths_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugin_name</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="../foundation-module/8-bdfw.html#SP6" class="function-link"><span class="function-syntax">Bibliographic::get_datum</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">weave_web</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TeX Mathematics Plugin"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">plugin_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"None"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">plugin_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hrs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">mathematics_plugin</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">plugin_name</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">R</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-tf.html#SP20" class="function-link"><span class="function-syntax">TeX::remove_math_mode</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-hf.html#SP12" class="function-link"><span class="function-syntax">HTMLFormat::escape_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">);</span>

2
docs/inweb/5-ptf.html
View file

@ -120,7 +120,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"unable to render unknown node"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure PlainText_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/tf, 5/hf, 5/df, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b><code class="display">
</pre><ul class="endnotetexts"><li>The structure PlainText_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/tf, 5/hf, 5/df, 5/wp, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Render head</span> <span class="named-paragraph-number">2.1</span>&gt; =
</code></p>

4
docs/inweb/5-rtt.html
View file

@ -47,13 +47,13 @@ function togglePopup(material_id) {
<ul class="toc"><li><a href="5-rtt.html#SP1">&#167;1. Running TeX</a></li><li><a href="5-rtt.html#SP4">&#167;4. Reporting</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Running TeX. </b>Although we are running <code class="display"><span class="extract-syntax">pdftex</span></code>, a modern variant of TeX, rather than the
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Running TeX. </b>Although we are running <span class="extract"><span class="extract-syntax">pdftex</span></span>, a modern variant of TeX, rather than the
original, they are very similar as command-line tools; the difference is
that the output is a PDF file rather than a DVI file, Knuth's original stab
at the same basic idea.
</p>
<p class="inwebparagraph">In particular, we call it in <code class="display"><span class="extract-syntax">-interaction=scrollmode</span></code> so that any errors
<p class="inwebparagraph">In particular, we call it in <span class="extract"><span class="extract-syntax">-interaction=scrollmode</span></span> so that any errors
whizz by rather than interrupting or halting the session. Because of that, we
spool the output onto a console file which we can then read in and parse to
find the number of errors actually generated. Prime among errors is the

47
docs/inweb/5-tf.html
View file

@ -172,7 +172,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"unable to render unknown node"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure TeX_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/ptf, 5/hf, 5/df, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b><code class="display">
</pre><ul class="endnotetexts"><li>The structure TeX_render_state is accessed in 1/ptt, 3/twot, 5/wt, 5/fm, 5/ptf, 5/hf, 5/df, 5/wp, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Render head</span> <span class="named-paragraph-number">2.1</span>&gt; =
</code></p>
@ -249,7 +249,7 @@ function togglePopup(material_id) {
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_11"></a><b>&#167;2.11. </b>TeX itself has an almost defiant lack of support for anything pictorial,
which is one reason it didn't live up to its hope of being the definitive basis
for typography; even today the loose confederation of TeX-like programs and
extensions lack standard approaches. Here we're going to use <code class="display"><span class="extract-syntax">pdftex</span></code> features,
extensions lack standard approaches. Here we're going to use <span class="extract"><span class="extract-syntax">pdftex</span></span> features,
having nothing better. All we're trying for is to insert a picture, scaled
to a given width, into the text at the current position.
</p>
@ -371,11 +371,7 @@ to a given width, into the text at the current position.
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_toc_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_weave_toc_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">trs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont %S."</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">text1</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">M</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">child</span><span class="plain-syntax">; </span><span class="identifier-syntax">M</span><span class="plain-syntax">; </span><span class="identifier-syntax">M</span><span class="plain-syntax"> = </span><span class="identifier-syntax">M</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP13" class="function-link"><span class="function-syntax">Trees::traverse_from</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">M</span><span class="plain-syntax">, &amp;</span><a href="5-hf.html#SP5" class="function-link"><span class="function-syntax">HTMLFormat::render_visit</span></a><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">trs</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">+1);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">M</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">next</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"; "</span><span class="plain-syntax">);</span>
@ -495,9 +491,9 @@ to a given width, into the text at the current position.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">displayed</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"$$"</span><span class="plain-syntax">); </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"$"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">displayed</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"$$"</span><span class="plain-syntax">); </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"$"</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1"></a><b>&#167;2.1.1. </b>We don't use TeX's <code class="display"><span class="extract-syntax">\input</span></code> mechanism for macros because it is so prone to
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP2">&#167;2</a>.</li></ul><p class="inwebparagraph"><a id="SP2_1_1"></a><b>&#167;2.1.1. </b>We don't use TeX's <span class="extract"><span class="extract-syntax">\input</span></span> mechanism for macros because it is so prone to
failures when searching directories (especially those with spaces in the
names) and then locking TeX into a repeated prompt for help from <code class="display"><span class="extract-syntax">stdin</span></code>
names) and then locking TeX into a repeated prompt for help from <span class="extract"><span class="extract-syntax">stdin</span></span>
which is rather hard to escape from.
</p>
@ -554,10 +550,7 @@ which is rather hard to escape from.
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text1</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text2</span><span class="plain-syntax">, </span><span class="reserved-syntax">paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">stage</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">:</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont %S."</span><span class="plain-syntax">, </span><span class="identifier-syntax">text1</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\medskip\\hrule\\smallskip\\par\\noindent{\\usagefont "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax">:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"; "</span><span class="plain-syntax">);</span>
@ -580,7 +573,6 @@ which is rather hard to escape from.
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">S</span><span class="plain-syntax">, </span><span class="reserved-syntax">section</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sections</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\smallskip\\noindent "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number_sections</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%d. "</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">printed_number</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"|%S|: "</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_range</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"{\\it %S}\\qquad\n%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_title</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_purpose</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
@ -605,7 +597,7 @@ which is rather hard to escape from.
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::clear</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">modified</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">modified</span><span class="plain-syntax">, </span><span class="string-syntax">"{\\sinchhigh %S}\\quad %S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">weight</span><span class="plain-syntax"> == </span><span class="constant-syntax">2</span><span class="plain-syntax">) &amp;&amp; ((</span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">is_a_singleton</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">)))</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">weight</span><span class="plain-syntax"> == </span><span class="constant-syntax">2</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\%S{%S}{%S}{%S}{\\%S}{%S}%%\n"</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TeX_macro</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="identifier-syntax">modified</span><span class="plain-syntax">, </span><span class="identifier-syntax">mark</span><span class="plain-syntax">, </span><span class="identifier-syntax">orn</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
@ -626,9 +618,9 @@ to pass the weight that way. Instead we use
<span class="plain-syntax"> \weavesectionss</span>
<span class="plain-syntax"> \weavesectionsss</span>
</pre>
<p class="inwebparagraph">where the weight is the number of terminal <code class="display"><span class="extract-syntax">s</span></code>s, 0 to 3. (TeX macros,
<p class="inwebparagraph">where the weight is the number of terminal <span class="extract"><span class="extract-syntax">s</span></span>s, 0 to 3. (TeX macros,
lamentably, are not allowed digits in their name.) In the cases 0 and 1, we
also have variants <code class="display"><span class="extract-syntax">\nsweavesection</span></code> and <code class="display"><span class="extract-syntax">\nsweavesections</span></code> which are
also have variants <span class="extract"><span class="extract-syntax">\nsweavesection</span></span> and <span class="extract"><span class="extract-syntax">\nsweavesections</span></span> which are
the same, but with the initial vertical spacing removed; these allow us to
prevent unsightly excess white space in certain configurations of a section.
</p>
@ -664,7 +656,7 @@ which follow the material on those pages: so that the running head for a page
can show the paragraph range for the material which tops it, for instance.
</p>
<p class="inwebparagraph">The ornament has to be set in math mode, even in the mark. <code class="display"><span class="extract-syntax">\S</span></code> and <code class="display"><span class="extract-syntax">\P</span></code>,
<p class="inwebparagraph">The ornament has to be set in math mode, even in the mark. <span class="extract"><span class="extract-syntax">\S</span></span> and <span class="extract"><span class="extract-syntax">\P</span></span>,
making a section sign and a pilcrow respectively, only work in math mode
because they abbreviate characters found in math fonts but not regular ones,
in TeX's deeply peculiar font encoding system.
@ -684,8 +676,7 @@ in TeX's deeply peculiar font encoding system.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">weight</span><span class="plain-syntax"> == </span><span class="constant-syntax">2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">sectionmark</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_title</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wv</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">show_abbrevs</span><span class="plain-syntax"> == </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">) </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::clear</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">chaptermark</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">sect_range</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><a href="../foundation-module/4-sm.html#SP17" class="function-link"><span class="function-syntax">Str::copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">chaptermark</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_range</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::clear</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">chaptermark</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP8" class="function-link"><span class="function-syntax">Str::len</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">chaptermark</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-sm.html#SP15" class="function-link"><span class="function-syntax">Str::clear</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">sectionmark</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">sectionmark</span><span class="plain-syntax">, </span><span class="string-syntax">" - %S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">sect_title</span><span class="plain-syntax">);</span>
@ -714,7 +705,7 @@ mode once again:
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">colour_wanted</span><span class="plain-syntax"> = </span><span class="constant-syntax">PLAIN_COLOUR</span><span class="plain-syntax">; </span>&lt;<span class="named-paragraph">Adjust code colour as necessary</span> <span class="named-paragraph-number">8.2</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8_1"></a><b>&#167;8.1. </b>We actually use <code class="display"><span class="extract-syntax">\qquad</span></code> horizontal spaces rather than risk using TeX's
</pre><p class="inwebparagraph"><a id="SP8_1"></a><b>&#167;8.1. </b>We actually use <span class="extract"><span class="extract-syntax">\qquad</span></span> horizontal spaces rather than risk using TeX's
messy alignment system:
</p>
@ -952,8 +943,8 @@ the special Preform grammar document.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="5-rtt.html#SP5" class="function-link"><span class="function-syntax">RunningTeX::substitute_post_processing_data</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">wv</span><span class="plain-syntax">, </span><span class="identifier-syntax">detail</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP20"></a><b>&#167;20. Removing math mode. </b>"Math mode", in TeX jargon, is what happens when a mathematical formula
is written inside dollar signs: in <code class="display"><span class="extract-syntax">Answer is $x+y^2$</span></code>, the math mode
content is <code class="display"><span class="extract-syntax">x+y^2</span></code>. But since math mode doesn't (easily) exist in HTML,
is written inside dollar signs: in <span class="extract"><span class="extract-syntax">Answer is $x+y^2$</span></span>, the math mode
content is <span class="extract"><span class="extract-syntax">x+y^2</span></span>. But since math mode doesn't (easily) exist in HTML,
for example, we want to strip it out if the format is not TeX-related.
To do this, the weaver calls the following.
</p>
@ -986,7 +977,7 @@ To do this, the weaver calls the following.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP20_1"></a><b>&#167;20.1. </b>Here we remove <code class="display"><span class="extract-syntax">{{top}\over{bottom}}</span></code>, converting it to <code class="display"><span class="extract-syntax">((top) / (bottom))</span></code>.
</pre><p class="inwebparagraph"><a id="SP20_1"></a><b>&#167;20.1. </b>Here we remove <span class="extract"><span class="extract-syntax">{{top}\over{bottom}}</span></span>, converting it to <span class="extract"><span class="extract-syntax">((top) / (bottom))</span></span>.
</p>
@ -1027,7 +1018,7 @@ To do this, the weaver calls the following.
<span class="plain-syntax"> </span><a href="5-tf.html#SP20" class="function-link"><span class="function-syntax">TeX::remove_math_mode_range</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">j</span><span class="plain-syntax">+2, </span><span class="identifier-syntax">to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP20">&#167;20</a>.</li></ul><p class="inwebparagraph"><a id="SP20_2"></a><b>&#167;20.2. </b>Here we remove <code class="display"><span class="extract-syntax">{\rm text}</span></code>, converting it to <code class="display"><span class="extract-syntax">text</span></code>, and similarly <code class="display"><span class="extract-syntax">\it</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP20">&#167;20</a>.</li></ul><p class="inwebparagraph"><a id="SP20_2"></a><b>&#167;20.2. </b>Here we remove <span class="extract"><span class="extract-syntax">{\rm text}</span></span>, converting it to <span class="extract"><span class="extract-syntax">text</span></span>, and similarly <span class="extract"><span class="extract-syntax">\it</span></span>.
</p>
@ -1049,8 +1040,8 @@ To do this, the weaver calls the following.
<span class="plain-syntax"> </span><a href="5-tf.html#SP20" class="function-link"><span class="function-syntax">TeX::remove_math_mode_range</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">j</span><span class="plain-syntax">+1, </span><span class="identifier-syntax">to</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP20">&#167;20</a>.</li></ul><p class="inwebparagraph"><a id="SP20_3"></a><b>&#167;20.3. </b>Here we remove <code class="display"><span class="extract-syntax">\sqrt{N}</span></code>, converting it to <code class="display"><span class="extract-syntax">sqrt(N)</span></code>. As a special case,
we also look out for <code class="display"><span class="extract-syntax">{}^3\sqrt{N}</span></code> for cube root.
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP20">&#167;20</a>.</li></ul><p class="inwebparagraph"><a id="SP20_3"></a><b>&#167;20.3. </b>Here we remove <span class="extract"><span class="extract-syntax">\sqrt{N}</span></span>, converting it to <span class="extract"><span class="extract-syntax">sqrt(N)</span></span>. As a special case,
we also look out for <span class="extract"><span class="extract-syntax">{}^3\sqrt{N}</span></span> for cube root.
</p>
@ -1214,7 +1205,7 @@ we also look out for <code class="display"><span class="extract-syntax">{}^3\sqr
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\\%S"</span><span class="plain-syntax">, </span><span class="reserved-syntax">macro</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP20_4">&#167;20.4</a>.</li></ul><p class="inwebparagraph"><a id="SP20_4_2"></a><b>&#167;20.4.2. </b>For Inform's purposes, we need to deal with just <code class="display"><span class="extract-syntax">\not\exists</span></code> and <code class="display"><span class="extract-syntax">\not\forall</span></code>.
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-tf.html#SP20_4">&#167;20.4</a>.</li></ul><p class="inwebparagraph"><a id="SP20_4_2"></a><b>&#167;20.4.2. </b>For Inform's purposes, we need to deal with just <span class="extract"><span class="extract-syntax">\not\exists</span></span> and <span class="extract"><span class="extract-syntax">\not\forall</span></span>.
</p>

74
docs/inweb/5-wp.html
View file

@ -50,7 +50,7 @@ function togglePopup(material_id) {
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Creation. </b>At present, plugins are simply their names: Inweb knows as little as possible
about how they work. The model is just that a file being woven either does or
does not need a plugin of a given name: for example, if it uses maths notation,
it will likely need the <code class="display"><span class="extract-syntax">MathJax3</span></code> plugin.
it will likely need the <span class="extract"><span class="extract-syntax">MathJax3</span></span> plugin.
</p>
<pre class="displayed-code all-displayed-code">
@ -62,7 +62,7 @@ it will likely need the <code class="display"><span class="extract-syntax">MathJ
</pre><ul class="endnotetexts"><li>The structure weave_plugin is accessed in 1/ts and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="function-syntax">WeavePlugins::new</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>WeavePlugins::new</b>:<br>The Swarm - <a href="1-ts.html#SP3">&#167;3</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP3_5">&#167;3.5</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="function-syntax">WeavePlugins::new</span><button class="popup" onclick="togglePopup('usagePopup1')">...<span class="popuptext" id="usagePopup1">Usage of <b>WeavePlugins::new</b>:<br>The Swarm - <a href="1-ts.html#SP3">&#167;3</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">plugin_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">))</span>
@ -113,8 +113,8 @@ actually look for: they will be available to some patterns and not others.
<span class="plain-syntax"> </span><span class="identifier-syntax">current_inclusion_round</span><span class="plain-syntax">++;</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>When a file is woven, then, the following function can add the plugins
necessary. If a plugin is called <code class="display"><span class="extract-syntax">X</span></code>, then we try to find <code class="display"><span class="extract-syntax">X.html</span></code> and
weave that into the page header; and we try to find <code class="display"><span class="extract-syntax">X.css</span></code>, weave an
necessary. If a plugin is called <span class="extract"><span class="extract-syntax">X</span></span>, then we try to find <span class="extract"><span class="extract-syntax">X.html</span></span> and
weave that into the page header; and we try to find <span class="extract"><span class="extract-syntax">X.css</span></span>, weave an
inclusion of that, and also copy the file into the weave destination.
</p>
@ -122,7 +122,7 @@ inclusion of that, and also copy the file into the weave destination.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">WeavePlugins::include_plugin</span><button class="popup" onclick="togglePopup('usagePopup4')">...<span class="popuptext" id="usagePopup4">Usage of <b>WeavePlugins::include_plugin</b>:<br>The Swarm - <a href="1-ts.html#SP3">&#167;3</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax">,</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">WeavePlugins::include_plugin</span><button class="popup" onclick="togglePopup('usagePopup4')">...<span class="popuptext" id="usagePopup4">Usage of <b>WeavePlugins::include_plugin</b>:<br>The Swarm - <a href="1-ts.html#SP3">&#167;3</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_plugin</span><span class="plain-syntax"> *</span><span class="identifier-syntax">wp</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_included_in_round</span><span class="plain-syntax"> == </span><span class="identifier-syntax">current_inclusion_round</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wp</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_included_in_round</span><span class="plain-syntax"> = </span><span class="identifier-syntax">current_inclusion_round</span><span class="plain-syntax">;</span>
@ -149,28 +149,27 @@ inclusion of that, and also copy the file into the weave destination.
<span class="plain-syntax"> </span><a href="3-ti.html#SP3" class="function-link"><span class="function-syntax">Indexer::incorporate_template_for_web_and_pattern</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">AP</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Use shell scripting to copy the file over</span> <span class="named-paragraph-number">5.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">html_mode</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/3-fln.html#SP8" class="function-link"><span class="function-syntax">Filenames::write_extension</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">".css"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">AP</span><span class="plain-syntax">) </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">from</span><span class="plain-syntax">), </span><span class="identifier-syntax">AP</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;link href=\"%S\" rel=\"stylesheet\" rev=\"stylesheet\" type=\"text/css\"&gt;\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">".js"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><a href="5-wp.html#SP6" class="function-link"><span class="function-syntax">WeavePlugins::include_CSS_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq_insensitive</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">".js"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">AP</span><span class="plain-syntax">) </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">from</span><span class="plain-syntax">), </span><span class="identifier-syntax">AP</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;script src=\"%S\"&gt;&lt;/script&gt;\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Use shell scripting to copy the file over</span> <span class="named-paragraph-number">5.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Use shell scripting to copy the file over</span> <span class="named-paragraph-number">5.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span>&lt;<span class="named-paragraph">Use shell scripting to copy the file over</span> <span class="named-paragraph-number">5.1</span>&gt;<span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">AP</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">finds</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> }</span>
@ -187,15 +186,24 @@ inclusion of that, and also copy the file into the weave destination.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">required</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b></p>
</pre><p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b><code class="display">
&lt;<span class="named-paragraph-defn">Use shell scripting to copy the file over</span> <span class="named-paragraph-number">5.1</span>&gt; =
</code></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">WeavePlugins::include_colour_scheme</span><button class="popup" onclick="togglePopup('usagePopup5')">...<span class="popuptext" id="usagePopup5">Usage of <b>WeavePlugins::include_colour_scheme</b>:<br>The Swarm - <a href="1-ts.html#SP3">&#167;3</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">colour_scheme</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cs</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">AP</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">as_ebook</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rel</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP2" class="function-link"><span class="function-syntax">Filenames::in</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/5-ee.html#SP5" class="function-link"><span class="function-syntax">Epub::note_image</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">, </span><span class="identifier-syntax">rel</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="5-wp.html#SP5">&#167;5</a> (four times).</li></ul><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b></p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">WeavePlugins::include_colour_scheme</span><button class="popup" onclick="togglePopup('usagePopup5')">...<span class="popuptext" id="usagePopup5">Usage of <b>WeavePlugins::include_colour_scheme</b>:<br>The Swarm - <a href="1-ts.html#SP3">&#167;3</a>&lt;br&gt;Patterns - <a href="1-ptt.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">colour_scheme</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cs</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_included_in_round</span><span class="plain-syntax"> == </span><span class="identifier-syntax">current_inclusion_round</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_included_in_round</span><span class="plain-syntax"> = </span><span class="identifier-syntax">current_inclusion_round</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="../foundation-module/4-sm.html#SP19" class="function-link"><span class="function-syntax">Str::eq</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">pattern_format</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">format_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"HTML"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">AP</span><span class="plain-syntax"> = </span><a href="6-cln.html#SP9" class="function-link"><span class="function-syntax">Colonies::assets_path</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">css</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">css</span><span class="plain-syntax">, </span><span class="string-syntax">"%S.css"</span><span class="plain-syntax">, </span><span class="identifier-syntax">cs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">scheme_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><a href="1-ptt.html#SP6" class="function-link"><span class="function-syntax">Patterns::find_asset</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Colouring"</span><span class="plain-syntax">, </span><span class="identifier-syntax">css</span><span class="plain-syntax">);</span>
@ -207,16 +215,36 @@ inclusion of that, and also copy the file into the weave destination.
<span class="plain-syntax"> </span><a href="1-pc.html#SP8" class="function-link"><span class="function-syntax">Main::error_in_web</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">AP</span><span class="plain-syntax">) </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">from</span><span class="plain-syntax">), </span><span class="identifier-syntax">AP</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">css</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;link href=\"%S\" rel=\"stylesheet\" rev=\"stylesheet\" type=\"text/css\"&gt;\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP8" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">AP</span><span class="plain-syntax">, </span><span class="identifier-syntax">cs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">prefix</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-wp.html#SP6" class="function-link"><span class="function-syntax">WeavePlugins::include_CSS_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">css</span><span class="plain-syntax">, </span><span class="identifier-syntax">cs</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">prefix</span><span class="plain-syntax">, </span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">css</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">WeavePlugins::include_CSS_file</span><button class="popup" onclick="togglePopup('usagePopup6')">...<span class="popuptext" id="usagePopup6">Usage of <b>WeavePlugins::include_CSS_file</b>:<br><a href="5-wp.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="constant-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">css</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">trans</span><span class="plain-syntax">, </span><span class="reserved-syntax">weave_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">, </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">embed_CSS</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;style type=\"text/css\"&gt;\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">css_file_transformation</span><span class="plain-syntax"> </span><span class="identifier-syntax">cft</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cft</span><span class="plain-syntax">.</span><span class="element-syntax">OUT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">OUT</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cft</span><span class="plain-syntax">.</span><span class="element-syntax">trans</span><span class="plain-syntax"> = </span><span class="identifier-syntax">trans</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-tf.html#SP5" class="function-link"><span class="function-syntax">TextFiles::read</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="constant-syntax">FALSE</span><span class="plain-syntax">, </span><span class="string-syntax">"can't open CSS file"</span><span class="plain-syntax">, </span><span class="constant-syntax">TRUE</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::transform_CSS</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">cft</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;/style&gt;\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">AP</span><span class="plain-syntax"> = </span><a href="6-cln.html#SP9" class="function-link"><span class="function-syntax">Colonies::assets_path</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">AP</span><span class="plain-syntax">) </span><a href="../foundation-module/3-pth.html#SP8" class="function-link"><span class="function-syntax">Pathnames::relative_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><a href="../foundation-module/3-fln.html#SP6" class="function-link"><span class="function-syntax">Filenames::up</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">from</span><span class="plain-syntax">), </span><span class="identifier-syntax">AP</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">css</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;link href=\"%S\" rel=\"stylesheet\" rev=\"stylesheet\" type=\"text/css\"&gt;\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">url</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ptt.html#SP7" class="function-link"><span class="function-syntax">Patterns::copy_file_into_weave</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">AP</span><span class="plain-syntax">, </span><span class="identifier-syntax">trans</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rel</span><span class="plain-syntax"> = </span><a href="../foundation-module/3-fln.html#SP2" class="function-link"><span class="function-syntax">Filenames::in</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">css</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/5-ee.html#SP5" class="function-link"><span class="function-syntax">Epub::note_image</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_ebook</span><span class="plain-syntax">, </span><span class="identifier-syntax">rel</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><hr class="tocbar">
<ul class="toc"><li><a href="5-df.html">Back to 'Debugging Format'</a></li><li><a href="5-rtt.html">Continue with 'Running Through TeX'</a></li></ul><hr class="tocbar">
<!--End of weave-->

22
docs/inweb/5-wt.html
View file

@ -546,7 +546,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">h</span><span class="plain-syntax"> = </span><span class="identifier-syntax">h</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP4" class="function-link"><span class="function-syntax">Trees::new_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">weave_embed_node_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_weave_embed_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>This node weaves an angle-bracketed paragraph macro name. <code class="display"><span class="extract-syntax">defn</span></code> is set
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>This node weaves an angle-bracketed paragraph macro name. <span class="extract"><span class="extract-syntax">defn</span></span> is set
if and only if this is the place where the macro is defined &mdash; the usual
thing is to render some sort of equals sign after it, if so.
</p>
@ -559,7 +559,7 @@ thing is to render some sort of equals sign after it, if so.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP4" class="function-link"><span class="function-syntax">Trees::new_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">weave_pmac_node_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_weave_pmac_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The following should render some kind of skip, and may want to take note of
whether this happens in commentary or in code: the <code class="display"><span class="extract-syntax">in_comment</span></code> flag provides this
whether this happens in commentary or in code: the <span class="extract"><span class="extract-syntax">in_comment</span></span> flag provides this
information.
</p>
@ -570,7 +570,7 @@ information.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP4" class="function-link"><span class="function-syntax">Trees::new_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">weave_vskip_node_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_weave_vskip_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>An opportunity for vertical tidying-up. At the beginning of a code
line which occurs after a run of <code class="display"><span class="extract-syntax">@d</span></code> or <code class="display"><span class="extract-syntax">@e</span></code> definitions, this node is
line which occurs after a run of <span class="extract"><span class="extract-syntax">@d</span></span> or <span class="extract"><span class="extract-syntax">@e</span></span> definitions, this node is
placed. It can then insert a little vertical gap to separate the code from
the definitions.
</p>
@ -685,7 +685,7 @@ definition has just occurred.
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">fn</span><span class="plain-syntax"> = </span><span class="identifier-syntax">fn</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP4" class="function-link"><span class="function-syntax">Trees::new_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">weave_function_defn_node_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_weave_function_defn_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>This node produces the <code class="display"><span class="extract-syntax">&gt;&gt; Example</span></code> bits of example source text, really
</pre><p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>This node produces the <span class="extract"><span class="extract-syntax">&gt;&gt; Example</span></span> bits of example source text, really
a convenience for Inform 7 code commentary.
</p>
@ -696,18 +696,18 @@ a convenience for Inform 7 code commentary.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="../foundation-module/2-trs.html#SP4" class="function-link"><span class="function-syntax">Trees::new_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">weave_display_line_node_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_weave_display_line_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>An item node produces an item marker in a typical (a), (b), (c), ... sort
of list. <code class="display"><span class="extract-syntax">depth</span></code> can be 1 or 2: you can have lists in lists, but not lists in
lists in lists. <code class="display"><span class="extract-syntax">label</span></code> is the marker text, e.g., <code class="display"><span class="extract-syntax">a</span></code>, <code class="display"><span class="extract-syntax">b</span></code>, <code class="display"><span class="extract-syntax">c</span></code>, ...; it can
of list. <span class="extract"><span class="extract-syntax">depth</span></span> can be 1 or 2: you can have lists in lists, but not lists in
lists in lists. <span class="extract"><span class="extract-syntax">label</span></span> is the marker text, e.g., <span class="extract"><span class="extract-syntax">a</span></span>, <span class="extract"><span class="extract-syntax">b</span></span>, <span class="extract"><span class="extract-syntax">c</span></span>, ...; it can
also be empty, in which case the method should move to the matching level of
indentation but not weave any bracketed marker.
</p>
</li><li>(a) This was produced by <code class="display"><span class="extract-syntax">depth</span></code> equal to 1, <code class="display"><span class="extract-syntax">label</span></code> equal to <code class="display"><span class="extract-syntax">a</span></code>.
<ul class="items"><li>(i) This was produced by <code class="display"><span class="extract-syntax">depth</span></code> equal to 2, <code class="display"><span class="extract-syntax">label</span></code> equal to <code class="display"><span class="extract-syntax">i</span></code>.
</li><li>(ii) This was produced by <code class="display"><span class="extract-syntax">depth</span></code> equal to 2, <code class="display"><span class="extract-syntax">label</span></code> equal to <code class="display"><span class="extract-syntax">ii</span></code>.
</li><li>(a) This was produced by <span class="extract"><span class="extract-syntax">depth</span></span> equal to 1, <span class="extract"><span class="extract-syntax">label</span></span> equal to <span class="extract"><span class="extract-syntax">a</span></span>.
<ul class="items"><li>(i) This was produced by <span class="extract"><span class="extract-syntax">depth</span></span> equal to 2, <span class="extract"><span class="extract-syntax">label</span></span> equal to <span class="extract"><span class="extract-syntax">i</span></span>.
</li><li>(ii) This was produced by <span class="extract"><span class="extract-syntax">depth</span></span> equal to 2, <span class="extract"><span class="extract-syntax">label</span></span> equal to <span class="extract"><span class="extract-syntax">ii</span></span>.
</li></ul>
<li> This was produced by <code class="display"><span class="extract-syntax">depth</span></code> equal to 1, <code class="display"><span class="extract-syntax">label</span></code> empty.
</li><li>(b) This was produced by <code class="display"><span class="extract-syntax">depth</span></code> equal to 1, <code class="display"><span class="extract-syntax">label</span></code> equal to <code class="display"><span class="extract-syntax">b</span></code>.
<li> This was produced by <span class="extract"><span class="extract-syntax">depth</span></span> equal to 1, <span class="extract"><span class="extract-syntax">label</span></span> empty.
</li><li>(b) This was produced by <span class="extract"><span class="extract-syntax">depth</span></span> equal to 1, <span class="extract"><span class="extract-syntax">label</span></span> equal to <span class="extract"><span class="extract-syntax">b</span></span>.
</p>
<pre class="displayed-code all-displayed-code">

32
docs/inweb/6-cln.html
View file

@ -69,38 +69,38 @@ Orb-Weaving Spiders With Communal Webbing in a Man-Made Structural Habitat
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colony</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">members</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">colony_member</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">members</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">colony_member</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">home</span><span class="plain-syntax">; </span><span class="comment"> path of home repository</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">assets_path</span><span class="plain-syntax">; </span><span class="comment"> where assets shared between weaves live</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">patterns_path</span><span class="plain-syntax">; </span><span class="comment"> where additional patterns live</span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">colony</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure colony is private to this section.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Each member is represented by an instance of the following. Note the <code class="display"><span class="extract-syntax">loaded</span></code>
</pre><ul class="endnotetexts"><li>The structure colony is private to this section.</li></ul><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Each member is represented by an instance of the following. Note the <span class="extract"><span class="extract-syntax">loaded</span></span>
field: this holds metadata on the web/module in question. (Recall that a module
is really just a web that doesn't tangle to an independent program but to a
library of code: for almost all purposes, it's a web.) But for efficiency's
sake, we read this metadata only on demand.
</p>
<p class="inwebparagraph">Note that the <code class="display"><span class="extract-syntax">path</span></code> might be either the name of a single-file web, or of a
<p class="inwebparagraph">Note that the <span class="extract"><span class="extract-syntax">path</span></span> might be either the name of a single-file web, or of a
directory holding a multi-section web.
</p>
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colony_member</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">web_rather_than_module</span><span class="plain-syntax">; </span><span class="comment"> </span><code class="display"><span class="extract-syntax">TRUE</span></code><span class="comment"> for a web, </span><code class="display"><span class="extract-syntax">FALSE</span></code><span class="comment"> for a module</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">; </span><span class="comment"> the </span><code class="display"><span class="extract-syntax">N</span></code><span class="comment"> in </span><code class="display"><span class="extract-syntax">N at P in W</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">path</span><span class="plain-syntax">; </span><span class="comment"> the </span><code class="display"><span class="extract-syntax">P</span></code><span class="comment"> in </span><code class="display"><span class="extract-syntax">N at P in W</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_path</span><span class="plain-syntax">; </span><span class="comment"> the </span><code class="display"><span class="extract-syntax">W</span></code><span class="comment"> in </span><code class="display"><span class="extract-syntax">N at P in W</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">home_leaf</span><span class="plain-syntax">; </span><span class="comment"> usually </span><code class="display"><span class="extract-syntax">index.html</span></code><span class="comment">, but not for single-file webs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">web_rather_than_module</span><span class="plain-syntax">; </span><span class="comment"> </span><span class="extract"><span class="extract-syntax">TRUE</span></span><span class="comment"> for a web, </span><span class="extract"><span class="extract-syntax">FALSE</span></span><span class="comment"> for a module</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">; </span><span class="comment"> the </span><span class="extract"><span class="extract-syntax">N</span></span><span class="comment"> in </span><span class="extract"><span class="extract-syntax">N at P in W</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">path</span><span class="plain-syntax">; </span><span class="comment"> the </span><span class="extract"><span class="extract-syntax">P</span></span><span class="comment"> in </span><span class="extract"><span class="extract-syntax">N at P in W</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">weave_path</span><span class="plain-syntax">; </span><span class="comment"> the </span><span class="extract"><span class="extract-syntax">W</span></span><span class="comment"> in </span><span class="extract"><span class="extract-syntax">N at P in W</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">home_leaf</span><span class="plain-syntax">; </span><span class="comment"> usually </span><span class="extract"><span class="extract-syntax">index.html</span></span><span class="comment">, but not for single-file webs</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">default_weave_pattern</span><span class="plain-syntax">; </span><span class="comment"> for use when weaving</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">web_md</span><span class="plain-syntax"> *</span><span class="identifier-syntax">loaded</span><span class="plain-syntax">; </span><span class="comment"> metadata on its sections, lazily evaluated</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">navigation</span><span class="plain-syntax">; </span><span class="comment"> navigation sidebar HTML</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">breadcrumb_tail</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">breadcrumb_request</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">breadcrumb_tail</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">breadcrumb_request</span></span>
<span class="plain-syntax"> </span><span class="constant-syntax">MEMORY_MANAGEMENT</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">colony_member</span><span class="plain-syntax">;</span>
</pre><ul class="endnotetexts"><li>The structure colony_member is accessed in 2/trs, 1/cnf, 1/ts, 3/ti, 5/wt, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>And the following reads a colony file <code class="display"><span class="extract-syntax">F</span></code> and produces a suitable <code class="display"><span class="extract-syntax">colony</span></code>
</pre><ul class="endnotetexts"><li>The structure colony_member is accessed in 2/trs, 1/cnf, 1/ts, 3/ti, 5/wt, 6/rw and here.</li></ul><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>And the following reads a colony file <span class="extract"><span class="extract-syntax">F</span></span> and produces a suitable <span class="extract"><span class="extract-syntax">colony</span></span>
object from it. This, for example, is the colony file for the Inweb repository
at GitHub:
</p>
@ -129,7 +129,7 @@ at GitHub:
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colony_reader_state</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">colony</span><span class="plain-syntax"> *</span><span class="identifier-syntax">province</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">nav</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">crumbs</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">breadcrumb_request</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">crumbs</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">breadcrumb_request</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pattern</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">colony_reader_state</span><span class="plain-syntax">;</span>
@ -276,7 +276,7 @@ the page, and this requests one.
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"li"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure breadcrumb_request is private to this section.</li></ul><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Searching. </b>Given a name <code class="display"><span class="extract-syntax">T</span></code>, we try to find a colony member of that name, returning the
</pre><ul class="endnotetexts"><li>The structure breadcrumb_request is private to this section.</li></ul><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. Searching. </b>Given a name <span class="extract"><span class="extract-syntax">T</span></span>, we try to find a colony member of that name, returning the
first we find.
</p>
@ -380,12 +380,12 @@ the data we already have; but if not, we read it in.
<span class="plain-syntax"> foundation: Text Streams</span>
<span class="plain-syntax"> goldbach</span>
</pre>
<p class="inwebparagraph">The reference text is in <code class="display"><span class="extract-syntax">text</span></code>; we return <code class="display"><span class="extract-syntax">TRUE</span></code> if we can make unambiguous
sense of it, or throw an error and return <code class="display"><span class="extract-syntax">FALSE</span></code> if not. If all is well, we
<p class="inwebparagraph">The reference text is in <span class="extract"><span class="extract-syntax">text</span></span>; we return <span class="extract"><span class="extract-syntax">TRUE</span></span> if we can make unambiguous
sense of it, or throw an error and return <span class="extract"><span class="extract-syntax">FALSE</span></span> if not. If all is well, we
must write a title and URL for the link.
</p>
<p class="inwebparagraph">The web metadata <code class="display"><span class="extract-syntax">Wm</span></code> is for the web currently being woven, and the line <code class="display"><span class="extract-syntax">L</span></code>
<p class="inwebparagraph">The web metadata <span class="extract"><span class="extract-syntax">Wm</span></span> is for the web currently being woven, and the line <span class="extract"><span class="extract-syntax">L</span></span>
is where the reference is made from.
</p>
@ -522,7 +522,7 @@ is where the reference is made from.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">title</span><span class="plain-syntax">, </span><span class="string-syntax">" (in %S)"</span><span class="plain-syntax">, </span><span class="identifier-syntax">search_CM</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name</span><span class="plain-syntax">);</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="6-cln.html#SP10_5">&#167;10.5</a>.</li></ul><p class="inwebparagraph"><a id="SP10_5_2"></a><b>&#167;10.5.2. </b>In the absence of a colony file, Inweb can really only guess, and the
guess it makes is that modules of the current web will be woven alongside
the main one, and suffixed by <code class="display"><span class="extract-syntax">-module</span></code>.
the main one, and suffixed by <span class="extract"><span class="extract-syntax">-module</span></span>.
</p>

2
docs/inweb/6-gs.html
View file

@ -45,7 +45,7 @@ function togglePopup(material_id) {
<!--Weave of 'Git Support' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#6">Chapter 6: Extras</a></li><li><b>Git Support</b></li></ul><p class="purpose">Constructing a suitable gitignore file for a simple inweb project.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This section offers just one function, which constructs a <code class="display"><span class="extract-syntax">.gitignore</span></code>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This section offers just one function, which constructs a <span class="extract"><span class="extract-syntax">.gitignore</span></span>
file by following a "prototype".
</p>

2
docs/inweb/6-mkf.html
View file

@ -57,7 +57,7 @@ following a "prototype".
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">inside_block</span><span class="plain-syntax">; </span><span class="comment"> scanning a "repeatblock" into that text?</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">last_line_was_blank</span><span class="plain-syntax">; </span><span class="comment"> used to suppress runs of multiple blank lines</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">allow_commands</span><span class="plain-syntax">; </span><span class="comment"> permit the prototype to use special commands</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">repeat_scope</span><span class="plain-syntax">; </span><span class="comment"> during a repeat, either </span><code class="display"><span class="extract-syntax">MAKEFILE_TOOL_MOM</span></code><span class="comment"> or </span><code class="display"><span class="extract-syntax">MAKEFILE_MODULE_MOM</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">repeat_scope</span><span class="plain-syntax">; </span><span class="comment"> during a repeat, either </span><span class="extract"><span class="extract-syntax">MAKEFILE_TOOL_MOM</span></span><span class="comment"> or </span><span class="extract"><span class="extract-syntax">MAKEFILE_MODULE_MOM</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">repeat_tag</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">dictionary</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tools_dictionary</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">dictionary</span><span class="plain-syntax"> *</span><span class="identifier-syntax">webs_dictionary</span><span class="plain-syntax">;</span>

22
docs/inweb/6-rw.html
View file

@ -45,7 +45,7 @@ function togglePopup(material_id) {
<!--Weave of 'Readme Writeme' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#6">Chapter 6: Extras</a></li><li><b>Readme Writeme</b></li></ul><p class="purpose">To construct Readme and similar files.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This is a very simple generator for <code class="display"><span class="extract-syntax">README.md</span></code> files, written in Markdown
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This is a very simple generator for <span class="extract"><span class="extract-syntax">README.md</span></span> files, written in Markdown
syntax, but with a few macro expansions of our own. The prototype file, which
uses these extra macros, is expanded to the final file, which does not.
</p>
@ -56,7 +56,7 @@ uses these extra macros, is expanded to the final file, which does not.
<pre class="displayed-code all-displayed-code">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">write_state</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">known_macros</span><span class="plain-syntax">; </span><span class="comment"> of </span><code class="display"><span class="extract-syntax">macro</span></code>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">known_macros</span><span class="plain-syntax">; </span><span class="comment"> of </span><span class="extract"><span class="extract-syntax">macro</span></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">macro</span><span class="plain-syntax"> *</span><span class="identifier-syntax">current_definition</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">macro_tokens</span><span class="plain-syntax"> *</span><span class="identifier-syntax">stack_frame</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">write_state</span><span class="plain-syntax">;</span>
@ -81,8 +81,8 @@ uses these extra macros, is expanded to the final file, which does not.
<span class="plain-syntax"> &amp;</span><a href="6-rw.html#SP2" class="function-link"><span class="function-syntax">Readme::write_helper</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">ws</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/2-str.html#SP34" class="function-link"><span class="function-syntax">Streams::close</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">file_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><ul class="endnotetexts"><li>The structure write_state is accessed in 1/ptt, 5/ptf, 5/tf, 5/hf, 5/df and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The file consists of definitions of macros, made one at a time, and
starting with <code class="display"><span class="extract-syntax">@define</span></code> and finishing with <code class="display"><span class="extract-syntax">@end</span></code>, and actual material.
</pre><ul class="endnotetexts"><li>The structure write_state is accessed in 1/ptt, 5/ptf, 5/tf, 5/hf, 5/df, 5/wp and here.</li></ul><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>The file consists of definitions of macros, made one at a time, and
starting with <span class="extract"><span class="extract-syntax">@define</span></span> and finishing with <span class="extract"><span class="extract-syntax">@end</span></span>, and actual material.
</p>
<pre class="displayed-code all-displayed-code">
@ -193,7 +193,7 @@ be used without breaking the flow.
<span class="plain-syntax"> </span><span class="identifier-syntax">from</span><span class="plain-syntax"> = </span><span class="identifier-syntax">x</span><span class="plain-syntax">+1;</span>
</pre><ul class="endnotetexts"><li>This code is used in <a href="6-rw.html#SP4">&#167;4</a> (twice).</li></ul><p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>So much for creating macros. Now we can write the actual expander. As can
be seen, it passes material straight through, except for instances of the
notation <code class="display"><span class="extract-syntax">@name</span></code>, possibly followed by a bracketed list of parameters.
notation <span class="extract"><span class="extract-syntax">@name</span></span>, possibly followed by a bracketed list of parameters.
</p>
<pre class="displayed-code all-displayed-code">
@ -213,7 +213,7 @@ notation <code class="display"><span class="extract-syntax">@name</span></code>,
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>If we run into the notation <code class="display"><span class="extract-syntax">@something</span></code>, it's possible that <code class="display"><span class="extract-syntax">something</span></code> is
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>If we run into the notation <span class="extract"><span class="extract-syntax">@something</span></span>, it's possible that <span class="extract"><span class="extract-syntax">something</span></span> is
the name of a parameter somewhere in the current stack, either on the top
frame or on frames lower down. The first match wins... and if there are no
matches, then it must be a macro name.
@ -246,9 +246,9 @@ matches, then it must be a macro name.
<span class="plain-syntax"> </span><a href="../foundation-module/3-em.html#SP5" class="function-link"><span class="function-syntax">Errors::in_text_file</span></a><span class="plain-syntax">(</span><span class="string-syntax">"no such @-command"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tfp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="constant-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"(command is '%S')\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">macro_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>So, then: suppose we have to expand <code class="display"><span class="extract-syntax">@example(5, gold rings)</span></code>. Then the
<code class="display"><span class="extract-syntax">macro_name</span></code> below is set to <code class="display"><span class="extract-syntax">example</span></code>, and the current stack frame contains the
values <code class="display"><span class="extract-syntax">5</span></code> and <code class="display"><span class="extract-syntax">gold rings</span></code>.
</pre><p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>So, then: suppose we have to expand <span class="extract"><span class="extract-syntax">@example(5, gold rings)</span></span>. Then the
<span class="extract"><span class="extract-syntax">macro_name</span></span> below is set to <span class="extract"><span class="extract-syntax">example</span></span>, and the current stack frame contains the
values <span class="extract"><span class="extract-syntax">5</span></span> and <span class="extract"><span class="extract-syntax">gold rings</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -404,7 +404,7 @@ assume that the version complies with any format).
<span class="plain-syntax"> </span><span class="identifier-syntax">A</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">version</span><span class="plain-syntax"> = </span><a href="../foundation-module/4-sm.html#SP3" class="function-link"><span class="function-syntax">Str::duplicate</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="element-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>Explicit code to read from <code class="display"><span class="extract-syntax">header.h</span></code> in the Inform 6 repository.
</pre><p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>Explicit code to read from <span class="extract"><span class="extract-syntax">header.h</span></span> in the Inform 6 repository.
</p>
<pre class="displayed-code all-displayed-code">
@ -434,7 +434,7 @@ assume that the version complies with any format).
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><a href="../foundation-module/4-pm.html#SP9" class="function-link"><span class="function-syntax">Regexp::dispose_of</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre><p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. </b>And this is needed for <code class="display"><span class="extract-syntax">cheapglk</span></code> and <code class="display"><span class="extract-syntax">glulxe</span></code> in the Inform repository.
</pre><p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. </b>And this is needed for <span class="extract"><span class="extract-syntax">cheapglk</span></span> and <span class="extract"><span class="extract-syntax">glulxe</span></span> in the Inform repository.
</p>
<pre class="displayed-code all-displayed-code">

442
docs/inweb/M-awwp.html
View file

@ -36,171 +36,371 @@
<main role="main">
<!--Weave of 'Advanced Weaving with Patterns' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</a></li><li><b>Advanced Weaving with Patterns</b></li></ul><p class="purpose">Customise the booklets woven from a web.</p>
<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>Advanced Weaving with Patterns</b></li></ul><p class="purpose">Customise your weave by creating a new pattern.</p>
<ul class="toc"><li><a href="M-awwp.html#SP1">&#167;1. Weave patterns</a></li><li><a href="M-awwp.html#SP4">&#167;4. Cover sheets</a></li><li><a href="M-awwp.html#SP5">&#167;5. Indexing</a></li></ul><hr class="tocbar">
<ul class="toc"><li><a href="M-awwp.html#SP1">&#167;1. Patterns versus formats</a></li><li><a href="M-awwp.html#SP3">&#167;3. Basic settings</a></li><li><a href="M-awwp.html#SP6">&#167;6. Plugins</a></li><li><a href="M-awwp.html#SP9">&#167;9. Embeddings</a></li><li><a href="M-awwp.html#SP10">&#167;10. Syntax colouring</a></li><li><a href="M-awwp.html#SP12">&#167;12. Templates</a></li><li><a href="M-awwp.html#SP15">&#167;15. Indexing</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Weave patterns. </b>As noted, the two most useful weave patterns are <code class="display"><span class="extract-syntax">-weave-as HTML</span></code> and
<code class="display"><span class="extract-syntax">-weave-as TeX</span></code>, and these are both supplied built in to Inweb. When you
weave something with <code class="display"><span class="extract-syntax">-weave-as P</span></code>, for some pattern name <code class="display"><span class="extract-syntax">P</span></code>, Inweb first
looks to see if the web in question defines a custom pattern of that name.
For example,
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Patterns versus formats. </b>Every weave produces output in a "format". The formats are built in to Inweb,
and adding new ones would mean contributing code to the project: currently
we have HTML, ePub, Plain Text, PDF, DIV, and TeX.
</p>
<p class="inwebparagraph">There is no way to specify the format at the command line. That's because
<span class="extract"><span class="extract-syntax">-weave-as P</span></span> tells Inweb to weave with a given "pattern": a weave pattern
combines a choice of format with other settings to produce a customised
weave. Patterns can also be based on other patterns: one can, in effect, say
"I want something like P but with some differences". For example, the Inweb
manual at GitHub is woven with <span class="extract"><span class="extract-syntax">-weave-as GitHubPages</span></span>, which is a pattern
based heavily on a generic website-producing pattern called <span class="extract"><span class="extract-syntax">HTML</span></span>.
</p>
<p class="inwebparagraph">The upshot of all this is that if you want a website, but one which looks and
behaves differently from what <span class="extract"><span class="extract-syntax">-weave-as HTML</span></span> would give, you should create
a new pattern based on it, and work from there. But patterns are not just
for websites.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>A pattern definition is a directory containing various files, which we'll
get to in due course. Inweb looks for patterns in three places in turn:
</p>
<ul class="items"><li>(a) The location given by the <span class="extract"><span class="extract-syntax">patterns</span></span> command in the current colony file,
if there is one: see <a href="M-mwiw.html" class="internal">Making Weaves into Websites</a>.
</li><li>(b) The <span class="extract"><span class="extract-syntax">Patterns</span></span> subdirectory of the current web, if there is a current web,
and if it has such a subdirectory.
</li><li>(c) The set of built-in patterns supplied with Inweb, at <span class="extract"><span class="extract-syntax">inweb/Patterns</span></span>
in the usual distribution.
</li></ul>
<p class="inwebparagraph">For example, the command
</p>
<pre class="ConsoleText-displayed-code all-displayed-code">
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inweb/Tangled/inweb</span><span class="ConsoleText-plain-syntax"> inweb/Examples/goldbach</span><span class="ConsoleText-identifier-syntax"> -weave-as</span><span class="ConsoleText-plain-syntax"> Tapestry</span>
</pre>
<p class="inwebparagraph">would look for a directory called:
<p class="inwebparagraph">didn't set a colony file, so (a) doesn't apply. Inweb first tries
<span class="extract"><span class="ConsoleText-extract-syntax">inweb/Examples/goldbach/Patterns/Tapestry</span></span> and then <span class="extract"><span class="ConsoleText-extract-syntax">inweb/Patterns/Tapestry</span></span>.
If it can't find either, Inweb issues an error.
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. Basic settings. </b>Patterns allow for extensive customisation of the woven output, especially
through the use of plugins (see below). But they can also be extremely minimal.
The one absolute requirement is to include a configuration file called
<span class="extract"><span class="ConsoleText-extract-syntax">pattern.txt</span></span>, which consists of a series of simple one-line commands.
In this file, blank lines, leading and trailing white space are all ignored,
as is any file whose first character is <span class="extract"><span class="ConsoleText-extract-syntax">#</span></span>.
</p>
<p class="inwebparagraph">The first genuine line of the file should always give the pattern's name,
and say what if anything it is based on. For example, this might be:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> inweb/Examples/goldbach/Patterns/Tapestry</span>
<span class="plain-syntax"> name: Tapestry based on HTML</span>
</pre>
<p class="inwebparagraph">If that is found, Inweb expects it to define <code class="display"><span class="extract-syntax">Tapestry</span></code>. If not, Inweb next
tries:
<p class="inwebparagraph">That is the only compulsory content; with that one line in one file, the
Tapestry pattern is ready for use. (But of course it behaves identically
to HTML in every respect, so it's not very useful yet.)
</p>
<p class="inwebparagraph">Do not get these into loops, with A based on B and B based on A.
</p>
<p class="inwebparagraph">For a pattern not based on an existing one, simply omit the "based on X"
part. Thus, for example,
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> inweb/Patterns/Tapestry</span>
<span class="plain-syntax"> name: HTML</span>
</pre><p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>There are then a handful of other, optional, settings. The following are
all inherited automatically from the pattern we are based on, unless we
set them ourselves.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> format: F</span>
</pre>
<p class="inwebparagraph">since <code class="display"><span class="extract-syntax">inweb/Patterns</span></code> is where the built-in patterns are kept. If it can't
find either, Inweb issues an error.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Patterns are a relatively new feature of Inweb, but allow for considerable
customisation of the woven output. In brief, a pattern directory is expected
to contain a configuration file called <code class="display"><span class="extract-syntax">pattern.txt</span></code>. This consists of a
series of simple one-line commands.
</p>
<p class="inwebparagraph">Most custom patterns open with the command:
<p class="inwebparagraph">sets the format. At present, this must be <span class="extract"><span class="extract-syntax">HTML</span></span>, <span class="extract"><span class="extract-syntax">plain</span></span> (plain text),
<span class="extract"><span class="extract-syntax">ePub</span></span>, <span class="extract"><span class="extract-syntax">TeX</span></span>, <span class="extract"><span class="extract-syntax">DVI</span></span>, or <span class="extract"><span class="extract-syntax">PDF</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> from Whatever</span>
<span class="plain-syntax"> number sections: yes</span>
<span class="plain-syntax"> number sections: no</span>
</pre>
<p class="inwebparagraph">which tells Inweb that this new pattern inherits from an existing one named
<code class="display"><span class="extract-syntax">Whatever</span></code>. (Do not get these into loops, with A inheriting from B and B
also inheriting from A.) The rule is then that if Inweb needs a file to do
with weaving, it looks first in the new custom pattern, and then, failing
that, in the pattern inherited from. As a result, the custom pattern need
only contain actual differences.
</p>
<p class="inwebparagraph">There should then always be a command reading:
<p class="inwebparagraph">causes the weaver to apply numbers to section headings: the first included will
be number 1, and so on. Default is <span class="extract"><span class="extract-syntax">no</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> format = HTML</span>
<span class="plain-syntax"> embed CSS: yes</span>
<span class="plain-syntax"> embed CSS: no</span>
</pre>
<p class="inwebparagraph">or whatever other file format is required (for the TeX pattern, for example,
this reads <code class="display"><span class="extract-syntax">format = PDF</span></code>). A few other settings can also be made with <code class="display"><span class="extract-syntax">=</span></code>.
</p>
<ul class="items"><li>(a) <code class="display"><span class="extract-syntax">numbered = yes</span></code> causes the weaver to apply numbers to section headings:
the first included will be number 1, and so on. Default is <code class="display"><span class="extract-syntax">no</span></code>.
</li><li>(b) <code class="display"><span class="extract-syntax">abbrevs = no</span></code> causes the weaver to suppress all mention of abbreviated
sections ranges, such as <code class="display"><span class="extract-syntax">2/tpc</span></code>, which aren't useful for documentation (for
example). Default is <code class="display"><span class="extract-syntax">yes</span></code>.
</li><li>(c) <code class="display"><span class="extract-syntax">tex-command = C</span></code> tells the weaver that the TeX typesetting system should
be invoked with the shell command <code class="display"><span class="extract-syntax">C</span></code>. Default is <code class="display"><span class="extract-syntax">tex</span></code>.
</li><li>(d) <code class="display"><span class="extract-syntax">pdftex-command = C</span></code> tells the weaver that the TeX typesetting system should
be invoked with the shell command <code class="display"><span class="extract-syntax">C</span></code> when what we want is a PDF, not a DVI
file. Default is <code class="display"><span class="extract-syntax">pdftex</span></code>.
</li><li>(e) <code class="display"><span class="extract-syntax">open-command = C</span></code> tells the weaver to use the shell command <code class="display"><span class="extract-syntax">C</span></code> if it
wants to open the woven file (i.e., on the user's computer) after it finishes.
Default is <code class="display"><span class="extract-syntax">open</span></code>, which works nicely for MacOS.
</li><li>(f) <code class="display"><span class="extract-syntax">default-range = R</span></code> tells the weaver to assume the range <code class="display"><span class="extract-syntax">R</span></code>, if the user
tries to weave a multi-section web with this pattern. (For example, the standard
HTML pattern sets <code class="display"><span class="extract-syntax">default-range = sections</span></code>.)
</li><li>(g) The equals sign can also be used to override values of the bibliographic data
for the web. These changes are only temporary for the period in which the weave
is going on; they enable us to give custom titles to different weaves from the
same web. For example:
<p class="inwebparagraph">causes the weaver to embed copies of CSS files into each HTML file it creates,
rather than to link to them. Default is <span class="extract"><span class="extract-syntax">no</span></span>, and there's no effect on non-HTML
formats.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> Title = Grammar</span>
<span class="plain-syntax"> Booklet Title = A formal grammar for Inform 7</span>
<span class="plain-syntax"> Author = The Inform Project</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The command:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> use X</span>
<span class="plain-syntax"> default range: R</span>
</pre>
<p class="inwebparagraph">tells Inweb that the file X, also stored in the pattern directory, should
be copied into any website being woven. For example, the HTML pattern says
<p class="inwebparagraph">tells the weaver to assume the range <span class="extract"><span class="extract-syntax">R</span></span>, if the user tries to weave a
multi-section web with this pattern. (For example, the standard HTML pattern
sets this to <span class="extract"><span class="extract-syntax">sections</span></span>, causing a swarm of individual HTML files to be produced.)
</p>
<p class="inwebparagraph">Lastly, there are commands to do with plugins, covered below, which are also
inherited.
</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>And there are a few settings which are not inherited: they apply only to the
pattern being defined, not to other patterns based on it.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> use crumbs.gif</span>
<span class="plain-syntax"> tex command: C</span>
</pre>
<p class="inwebparagraph">to instruct Inweb that an image used by the pages generated needs to be
copied over.
</p>
<p class="inwebparagraph">Finally, the command
<p class="inwebparagraph">tells the weaver that the TeX typesetting system should be invoked with the
shell command <span class="extract"><span class="extract-syntax">C</span></span>. Default is <span class="extract"><span class="extract-syntax">tex</span></span>. Similarly for <span class="extract"><span class="extract-syntax">pdftex command: C</span></span>, used
when we want to make a PDF rather than a DVI.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> embed css</span>
<span class="plain-syntax"> open command: C</span>
</pre>
<p class="inwebparagraph">tells Inweb that in any HTML file produced, the CSS necessary should be
embedded into the HTML, not linked as an external file. This is tidier for
patterns like TeX, where there will only be at most one HTML file produced,
and there's no need for an external CSS file.
</p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. Cover sheets. </b>If a weave has a range bigger than a single section &mdash; for example, if it's
a weave of a chapter, or of the complete web &mdash; then it will include a
"cover sheet". In the case of a PDF being made via TeX, this will actually
be an extra page at the front of the PDF; for HTML, of course, it will just
be additional material at the top of the web page.
</p>
<p class="inwebparagraph">The template for the cover sheet should be given in a file in the pattern
folder called <code class="display"><span class="extract-syntax">cover-sheet.tex</span></code>, <code class="display"><span class="extract-syntax">cover-sheet.html</span></code> or similar. Within it,
double-square brackets can be used to represent values from the bibliographic
data at the top of the web's Contents section. For example:
<p class="inwebparagraph">tells the weaver to use the shell command <span class="extract"><span class="extract-syntax">C</span></span> if it wants to open the woven
file (i.e., on the user's computer) after it finishes. Default is <span class="extract"><span class="extract-syntax">open</span></span>,
which works nicely for MacOS.
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> \noindent{{\stitlefont </span><span class="function-syntax">[[Author]]</span><span class="plain-syntax">}}</span>
<span class="plain-syntax"> bibliographic data: K = V</span>
</pre>
<p class="inwebparagraph">In addition:
<p class="inwebparagraph">tells the weaver to override the bibliographic data on any web it weaves, setting
the key <span class="extract"><span class="extract-syntax">K</span></span> to the value <span class="extract"><span class="extract-syntax">V</span></span>. For example:
</p>
</li><li>(a) <code class="display"><span class="extract-syntax">[[Cover Sheet]]</span></code> expands to the parent pattern's cover sheet &mdash; this is
convenient if all you want to do is to add a note at the bottom of the
standard look.
</li><li>(b) <code class="display"><span class="extract-syntax">[[Booklet Title]]</span></code> expands to text such as "Chapter 3", appropriate
to the weave being made.
</li><li>(c) <code class="display"><span class="extract-syntax">[[Capitalized Title]]</span></code> is a form of the title in block capital letters.
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> bibliographic data: Booklet Title = A formal grammar for Inform 7</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. Plugins. </b>Plugins are named bundles of resources which are sometimes added to a weave,
and sometimes not, depending on its needs; they are placed in the pattern's
folder, and Inweb has access to the plugins not only for the current pattern,
but also for any pattern(s) it is based on. Plugins were designed for HTML,
but there's no reason they shouldn't also be useful for other formats.
</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Indexing. </b>Some weaves are accompanied by indexes. For example, a standard weave into
sections (for the HTML pattern) generates an <code class="display"><span class="extract-syntax">index.html</span></code> contents page,
linking to the weaves for the individual sections. How is this done?
<p class="inwebparagraph">A plugin is identified by name alone, case-insensitively, and that name should
be a single alphanumeric word. For example, the HTML pattern file says
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> plugin: Base</span>
</pre>
<p class="inwebparagraph">and this ensures that every file woven by this pattern, or any pattern based
on it, will use <span class="extract"><span class="extract-syntax">Base</span></span>. There can be multiple such commands, for multiple such
plugins, and the ability isn't restricted to HTML alone.
</p>
<p class="inwebparagraph">In addition, the HTML format:
</p>
<ul class="items"><li>(a) includes <span class="extract"><span class="extract-syntax">MathJax3</span></span> if the woven file needs mathematics notation;
</li><li>(b) includes <span class="extract"><span class="extract-syntax">Breadcrumbs</span></span> if it has a breadcrumb navigation trail;
</li><li>(c) includes <span class="extract"><span class="extract-syntax">Carousel</span></span> if it has any image carousels;
</li><li>(d) includes <span class="extract"><span class="extract-syntax">Popups</span></span> if it has any clickable popups (for example, to show
function usage);
</li><li>(e) includes <span class="extract"><span class="extract-syntax">Bigfoot</span></span> if it includes footnotes.
</li></ul>
<p class="inwebparagraph">Two of these draw on other open-source projects:
</p>
<ul class="items"><li>(a) <span class="extract"><span class="extract-syntax">MathJax3</span></span> is an excellent rendering system for mathematics on the web: see
<a href="https://docs.mathjax.org/en/latest/index.html" class="external">https://docs.mathjax.org/en/latest/index.html</a>
</li><li>(b) <span class="extract"><span class="extract-syntax">Bigfoot</span></span> is adapted from a popularly used piece of web coding: see
<a href="https://github.com/lemonmade/bigfoot" class="external">https://github.com/lemonmade/bigfoot</a>
</li></ul>
<p class="inwebparagraph">But if you would like your pattern to use different plugins to handle
mathematics and footnoting, provide lines like these in your pattern file,
but with your preferred plugin names:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> mathematics plugin: MathJax3</span>
<span class="plain-syntax"> footnotes plugin: Bigfoot</span>
</pre>
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">Bigfoot</span></span> may eventually need to be simplified and rewritten: its big feet
presently tread on the <span class="extract"><span class="extract-syntax">MathJax3</span></span> plugin, so right now it's not possible to
have mathematics in a footnote when <span class="extract"><span class="extract-syntax">Bigfoot</span></span> is in use.
</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>It's also possible to supply your own version of any plugin you would like
to tinker with. If you want <span class="extract"><span class="extract-syntax">Carousel</span></span> to have rather different CSS effects,
for example, make your own copy of <span class="extract"><span class="extract-syntax">Carousel</span></span> (copying it from the one in
the Inweb distribution at <span class="extract"><span class="extract-syntax">inweb/Patterns/HTML/Carousel</span></span>) and place it in your
own pattern. Your version will prevail over the built-in one.
</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>So what's in a plugin? There's not much to it. Every file in a plugin, whose
name does not begin with a <span class="extract"><span class="extract-syntax">.</span></span>, is copied into the weave: that means it either
gets copied to the weave destination directory, or possibly to the <span class="extract"><span class="extract-syntax">assets</span></span>
directory specified in the colony file (if there is one). However:
</p>
<ul class="items"><li>(a) If the format is HTML, and the filename ends <span class="extract"><span class="extract-syntax">.css</span></span>, then a link to the
CSS file is automatically included in the head of the file. If the pattern
says to <span class="extract"><span class="extract-syntax">embed CSS</span></span> (see above), then the file is spliced in rather than
being copied.
</li><li>(b) If the format is HTML, and the filename ends <span class="extract"><span class="extract-syntax">.js</span></span>, then a link to the
Javascript file is automatically included in the head of the file.
</li></ul>
<p class="inwebparagraph">For example, the <span class="extract"><span class="extract-syntax">Breadcrumbs</span></span> plugin contains an image file and a CSS file;
both are copied across, but a link to the CSS file is also included in the
woven file needing to use the plugin.
</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Embeddings. </b>Patterns with the HTML format may also want to provide "embeddings". These
are for embedded video/audio or other gadgets, and each different "service" &mdash;
<span class="extract"><span class="extract-syntax">YouTube</span></span>, <span class="extract"><span class="extract-syntax">SoundCloud</span></span>, and such &mdash; is represented by an embedding file.
Inweb looks for these in the pattern's <span class="extract"><span class="extract-syntax">Embedding</span></span> subdirectory, if there is
one; then it tries in the pattern we are based on, and so on until it gives
up and throws an error.
</p>
<p class="inwebparagraph">The services in the standard Inweb installation, then, are in
<span class="extract"><span class="extract-syntax">inweb/Patterns/HTML/Embeddings</span></span>. It's easy to add new ones; for example,
by creating a similar fragment in <span class="extract"><span class="extract-syntax">Tapestry/Embedding/WebTubeo.html</span></span> you
would provide for embedding videos from <span class="extract"><span class="extract-syntax">WebTubeo</span></span> when using your pattern.
</p>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. Syntax colouring. </b>No two people ever agree on the ideal colour scheme for syntax-colouring,
so one prime reason to create a custom pattern is to change Inweb's defaults.
</p>
<p class="inwebparagraph">Suppose Inweb wants to weave an extract of code written in, say, C. It will
use the programming language definition for C to make a syntax-colouring,
but then use the weave pattern to decide the colour scheme. For example,
it's up to the C language to say which text is a function name: but it's up
to the pattern to say whether functions are red or green.
</p>
<p class="inwebparagraph">A pattern based on HTML may provide a subdirectory called <span class="extract"><span class="extract-syntax">Colouring</span></span>. If it
does, then the contents will be CSS files which provide colour schemes for
different programming languages. The scheme <span class="extract"><span class="extract-syntax">Colours.css</span></span> is the fallback,
and is used for any language not providing a colour scheme; otherwise, a
language called, say, <span class="extract"><span class="extract-syntax">Anaconda</span></span> would be coloured by <span class="extract"><span class="extract-syntax">Anaconda-Colours.css</span></span>.
Inweb looks first in the <span class="extract"><span class="extract-syntax">Colouring</span></span> directory of the current pattern, then
tries the pattern it is based on, and so on.
</p>
<p class="inwebparagraph">The practical effect is that if you want a pattern to colour Anaconda programs
in your own preferred way &mdash; let's call this hypothetical pattern <span class="extract"><span class="extract-syntax">SnakeSkin</span></span> &mdash;
then you need only write two files: <span class="extract"><span class="extract-syntax">SnakeSkin/pattern.txt</span></span>, consisting of
the single line
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> name: SnakeSkin based on HTML</span>
</pre>
<p class="inwebparagraph">(or perhaps based on <span class="extract"><span class="extract-syntax">GitHubPages</span></span>, if you want to host there); and then
a colouring file in <span class="extract"><span class="extract-syntax">SnakeSkin/Colouring/Anaconda-Colours.css</span></span>. You should
make this by copying the default <span class="extract"><span class="extract-syntax">Colours.css</span></span> and tinkering.
</p>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>Note that Inweb supports multiple languages in the same weave, each having
their own colour schemes. To do this, it renames CSS spans on the fly in
order to prevent namespace clashes. But you can forget this, because it's
automatic.
</p>
<p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. Templates. </b>The final possible ingredient for a pattern is a "template"; this is a file
like a pro-forma letter, into which just the details need to be entered.
At present, Inweb does this in four circumstances:
</p>
<ul class="items"><li>(a) After a weave which ranges over more than a single section &mdash; for example,
if it's a weave of a chapter, or of the complete web &mdash; Inweb can generate
an "index". (This is more often a contents page, but Inweb uses the generic
term "index".) For this, it uses <span class="extract"><span class="extract-syntax">unchaptered-index.html</span></span> if the web has
sections but no chapters; or <span class="extract"><span class="extract-syntax">chaptered-index.html</span></span> if it has chapters. If
Inweb can't locate either of those, it looks simply for <span class="extract"><span class="extract-syntax">index.html</span></span>, and
if it can't find that either then it gives up.
</li><li>(b) Similarly, after a weave which is not a single section, Inweb looks to
see if there is <span class="extract"><span class="extract-syntax">cover-sheet.XXX</span></span> template, in whatever format is being used:
<span class="extract"><span class="extract-syntax">cover-sheet.tex</span></span>, or <span class="extract"><span class="extract-syntax">cover-sheet.html</span></span>, as appropriate. This is placed at
the start of the material, and can be, e.g., a fancily typeset title page:
it's a feature intended more for serial formats than for the web.
</li><li>(c) A weave using the HTML format is built around a pro-forma <span class="extract"><span class="extract-syntax">template.html</span></span>.
This is required to exist and defines the overall shape of the HTML pages
which Inweb weaves.
</li><li>(d) When one template wants to use another one &mdash; i.e., as a consequence of
reasons (a) or (b).
</li></ul>
<p class="inwebparagraph">As with other pattern-related resources, when Inweb needs to find, say,
<span class="extract"><span class="extract-syntax">template.html</span></span>, it looks first in the current pattern's directory, then
tries the pattern this is based on, and so on. You can therefore override
the standard HTML pattern's <span class="extract"><span class="extract-syntax">template.html</span></span> by placing your own in your
new pattern.
</p>
<p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. </b>For example, here is a template file for making an HTML page:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax">&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"&gt;</span>
<span class="plain-syntax">&lt;html&gt;</span>
<span class="plain-syntax"> &lt;head&gt;</span>
<span class="plain-syntax"> &lt;title&gt;</span><span class="function-syntax">[[Booklet Title]]</span><span class="plain-syntax">&lt;/title&gt;</span>
<span class="plain-syntax"> </span><span class="function-syntax">[[Plugins]]</span>
<span class="plain-syntax"> &lt;/head&gt;</span>
<span class="plain-syntax"> &lt;body&gt;</span>
<span class="function-syntax">[[Code]]</span>
<span class="plain-syntax"> &lt;/body&gt;</span>
<span class="plain-syntax">&lt;/html&gt;</span>
</pre>
<p class="inwebparagraph">The weaver uses this to generate any HTML page of program taken from the
web being woven. (I.e., it doesn't use it to generate the index: only to
generate the pages for sections or chapters.) What you see is what you get,
except for the placeholders in double square brackets:
</p>
<ul class="items"><li>(a) <span class="extract"><span class="extract-syntax">[[Code]]</span></span> expands to the body of the web page &mdash; the headings,
paragraphs and so on.
</li><li>(b) <span class="extract"><span class="extract-syntax">[[Plugins]]</span></span> expands to any links to CSS or Javascript files needed
by the plugins being used &mdash; see above.
</li><li>(c) Any bibliographic datum for the web expands to its value: thus <span class="extract"><span class="extract-syntax">[[Title]]</span></span>,
<span class="extract"><span class="extract-syntax">[[Author]]</span></span> and so on. Booklet Title is one of these, but the weaver always
sets it to a sensible title for the current file being woven &mdash; typically the
name of a section or chapter, if that's what the file will contain. Another
sometimes useful case to know is <span class="extract"><span class="extract-syntax">[[Capitalized Title]]</span></span>, which is the title
in BLOCK CAPITAL LETTERS.
</p>
<p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. </b>Other placeholders, not used in the example above, include:
</p>
</li><li>(a) <span class="extract"><span class="extract-syntax">[[Template X]]</span></span> expands to an insertion of the template file <span class="extract"><span class="extract-syntax">X</span></span>.
</li><li>(b) <span class="extract"><span class="extract-syntax">[[Navigation]]</span></span> expands to the navigation sidebar in use when weaving
a colony of webs &mdash; see <a href="M-mwiw.html" class="internal">Making Weaves into Websites</a> for more, and for
syntaxes to do with links and URLs.
</li><li>(c) <span class="extract"><span class="extract-syntax">[[Breadcrumbs]]</span></span> expands to the HTML for the breadcrumb trail.
</p>
<p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. Indexing. </b>As noted above, some weaves are accompanied by indexes. For example, a
standard weave into sections (for the HTML pattern) generates an <span class="extract"><span class="extract-syntax">index.html</span></span>
contents page, linking to the weaves for the individual sections. How is this
done?
</p>
<p class="inwebparagraph">Inweb looks in the pattern for a template file called either
<code class="display"><span class="extract-syntax">chaptered-index.html</span></code> or <code class="display"><span class="extract-syntax">unchaptered-index.html</span></code>, according to whether the
web's sections are in chapters or simply in a single directory of <code class="display"><span class="extract-syntax">Sections</span></code>.
If it doesn't find this, it looks for a template simply called <code class="display"><span class="extract-syntax">index.html</span></code>,
<span class="extract"><span class="extract-syntax">chaptered-index.html</span></span> or <span class="extract"><span class="extract-syntax">unchaptered-index.html</span></span>, according to whether the
web's sections are in chapters or simply in a single directory of <span class="extract"><span class="extract-syntax">Sections</span></span>.
If it doesn't find this, it looks for a template simply called <span class="extract"><span class="extract-syntax">index.html</span></span>,
using that template in either case.
</p>
<p class="inwebparagraph">An index is then made by taking this template file and running it through
the "template interpreter". This is basically a filter: that is, it
works through one line at a time, and most of the time it simply copies
the input to the output. The filtering consists of making the following
replacements. Any text in the form <code class="display"><span class="extract-syntax">[[...]]</span></code> is substituted with the
value <code class="display"><span class="extract-syntax">...</span></code>, which can be any of:
<p class="inwebparagraph">Now, however, there are additional double-squared placeholders available:
</p>
</li><li>(a) A bibliographic variable, set at the top of the <code class="display"><span class="extract-syntax">Contents.w</span></code> section.
</li><li>(b) One of the following details about the entire-web PDF (see below):
</li><li>(a) One of the following details about the entire-web PDF (see below):
</p>
<pre class="displayed-code all-displayed-code">
@ -231,24 +431,24 @@ the errors result is a usually blank report.
<p class="inwebparagraph"></p>
</li><li> Lines and Paragraphs are counts of the number of each; the Source
substitution is the leafname of the original <code class="display"><span class="extract-syntax">.w</span></code> file. The Mean is the
substitution is the leafname of the original <span class="extract"><span class="extract-syntax">.w</span></span> file. The Mean is the
average number of lines per paragraph: where this is large, the section
is rather raw and literate programming is not being used to the full.
</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>But the template interpreter isn't merely "editing the stream", because
it can also handle repetitions. The following commands must occupy entire
lines:
<p class="inwebparagraph"><a id="SP16"></a><b>&#167;16. </b>And here the indexer isn't merely "editing the stream" of the template,
because it can also handle repetitions. The following commands must occupy
entire lines:
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">[[Repeat Chapter]]</span></code> and <code class="display"><span class="extract-syntax">[[Repeat Section]]</span></code> begin blocks of lines which
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">[[Repeat Chapter]]</span></span> and <span class="extract"><span class="extract-syntax">[[Repeat Section]]</span></span> begin blocks of lines which
are repeated for each chapter or section: the material to be repeated
continues to the matching <code class="display"><span class="extract-syntax">[[End Repeat]</span></code> line. The ``current chapter or
continues to the matching <span class="extract"><span class="extract-syntax">[[End Repeat]</span></span> line. The ``current chapter or
section'' mentioned above is the one selected in the current innermost
loop of that description.
</p>
<p class="inwebparagraph"><code class="display"><span class="extract-syntax">[[Select ...]]</span></code> and <code class="display"><span class="extract-syntax">[[End Select]</span></code> form a block which behaves like
<p class="inwebparagraph"><span class="extract"><span class="extract-syntax">[[Select ...]]</span></span> and <span class="extract"><span class="extract-syntax">[[End Select]</span></span> form a block which behaves like
a repetition, but happens just once, for the named chapter or section.
</p>

153
docs/inweb/M-htwaw.html
View file

@ -58,11 +58,11 @@ MathJax = {
<!--Weave of 'How to Write a Web' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</a></li><li><b>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="M-htwaw.html#SP1">&#167;1. The title of a section</a></li><li><a href="M-htwaw.html#SP2">&#167;2. Paragraphing</a></li><li><a href="M-htwaw.html#SP6">&#167;6. Conditional compilation</a></li><li><a href="M-htwaw.html#SP7">&#167;7. Commentary</a></li><li><a href="M-htwaw.html#SP12">&#167;12. Code samples and other extraneous matter</a></li><li><a href="M-htwaw.html#SP13">&#167;13. Links</a></li><li><a href="M-htwaw.html#SP14">&#167;14. Cross-references</a></li><li><a href="M-htwaw.html#SP18">&#167;18. Figures</a></li><li><a href="M-htwaw.html#SP19">&#167;19. Carousels</a></li><li><a href="M-htwaw.html#SP20">&#167;20. Embedded video</a></li><li><a href="M-htwaw.html#SP23">&#167;23. Mathematics notation</a></li><li><a href="M-htwaw.html#SP24">&#167;24. Footnotes</a></li></ul><hr class="tocbar">
<ul class="toc"><li><a href="M-htwaw.html#SP1">&#167;1. The title of a section</a></li><li><a href="M-htwaw.html#SP2">&#167;2. Paragraphing</a></li><li><a href="M-htwaw.html#SP6">&#167;6. Conditional compilation</a></li><li><a href="M-htwaw.html#SP7">&#167;7. Commentary</a></li><li><a href="M-htwaw.html#SP12">&#167;12. Code samples and other extraneous matter</a></li><li><a href="M-htwaw.html#SP13">&#167;13. Links</a></li><li><a href="M-htwaw.html#SP14">&#167;14. Cross-references</a></li><li><a href="M-htwaw.html#SP18">&#167;18. Figures</a></li><li><a href="M-htwaw.html#SP19">&#167;19. Carousels</a></li><li><a href="M-htwaw.html#SP20">&#167;20. Embedded video</a></li><li><a href="M-htwaw.html#SP22">&#167;22. Mathematics notation</a></li><li><a href="M-htwaw.html#SP23">&#167;23. Footnotes</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;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-syntax">@</span></code> character.)
line which starts with an <span class="extract"><span class="extract-syntax">@</span></span> character.)
</p>
<p class="inwebparagraph">The first line should be the title of the section, followed by a full stop.
@ -85,7 +85,7 @@ which must be given in round brackets and followed by a colon:
<span class="plain-syntax"> (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-syntax">S/tsoe</span></code>.
abbreviation itself: in this case, it comes up with <span class="extract"><span class="extract-syntax">S/tsoe</span></span>.
</p>
<p class="inwebparagraph">Subsequent lines of text are then taken as the optional description of the
@ -95,7 +95,7 @@ example:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> A fairly fast way to determine if small numbers are prime, given storage.</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Paragraphing. </b>A standard paragraph is introduced with an <code class="display"><span class="extract-syntax">@</span></code> command, which must place
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;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>
@ -103,7 +103,7 @@ that magic character in the first column of the line:
<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="inwebparagraph">A fancier paragraph with a subheading attached is introduced using the
<code class="display"><span class="extract-syntax">@h</span></code> or <code class="display"><span class="extract-syntax">@heading</span></code> command instead. (This is simply a long and short version
<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>
@ -132,17 +132,17 @@ example shows all three being used:
<span class="plain-syntax"> return FALSE;</span>
<span class="plain-syntax"> return TRUE;</span>
<span class="plain-syntax"> }</span>
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Definitions are made using one of three commands: <code class="display"><span class="extract-syntax">@d</span></code> or <code class="display"><span class="extract-syntax">@define</span></code>; or
<code class="display"><span class="extract-syntax">@e</span></code> or <code class="display"><span class="extract-syntax">@enum</span></code>; or <code class="display"><span class="extract-syntax">@default</span></code>, which is rarely used and has no abbreviation.
</pre><p class="inwebparagraph"><a id="SP3"></a><b>&#167;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 <code class="display"><span class="extract-syntax">#define</span></code> directive in C. <code class="display"><span class="extract-syntax">@define</span></code> is the simpler form.
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">
<span class="plain-syntax"> </span><span class="function-syntax">@define</span><span class="plain-syntax"> ENIGMATIC_NUMBER 90125</span>
</pre>
<p class="inwebparagraph">sets <code class="display"><span class="extract-syntax">ENIGMATIC_NUMBER</span></code> to 90125. Unlike in the C preprocessor, multi-line
<p class="inwebparagraph">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>
@ -164,7 +164,7 @@ 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-syntax">@enum</span></code> are a convenience to define enumerated constants.
<p class="inwebparagraph">Enumerations with <span class="extract"><span class="extract-syntax">@enum</span></span> are a convenience to define enumerated constants.
For example,
</p>
@ -181,21 +181,21 @@ For example,
<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="inwebparagraph">What happens is that <code class="display"><span class="extract-syntax">@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-syntax">_MNTH</span></code>. The first time an enumerated
value is asked for with this tail, <code class="display"><span class="extract-syntax">from</span></code> is used to specify the lowest
<p class="inwebparagraph">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 <code class="display"><span class="extract-syntax">_MNTH</span></code> request, <code class="display"><span class="extract-syntax">@enum</span></code> allocates the next unused value.
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="inwebparagraph">All symbols defined with <code class="display"><span class="extract-syntax">@define</span></code> or <code class="display"><span class="extract-syntax">@enum</span></code> are global, and can be used
<p class="inwebparagraph">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="inwebparagraph">A symbol defined with <code class="display"><span class="extract-syntax">@default</span></code> has the given value only if some other use
of <code class="display"><span class="extract-syntax">@d</span></code> or <code class="display"><span class="extract-syntax">@e</span></code> in the web has not already defined it. For example, if the
<p class="inwebparagraph">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>
@ -250,9 +250,9 @@ rather than at its natural place in the sequence, by annotating
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> = (early code)</span>
</pre>
<p class="inwebparagraph">instead of just <code class="display"><span class="extract-syntax">=</span></code>. (This is occasionally useful where, for example, it's
<p class="inwebparagraph">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 <code class="display"><span class="extract-syntax">= (very early code)</span></code> can be used in C
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>
@ -268,15 +268,15 @@ of that extract. For example:
<span class="plain-syntax"> 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-syntax">@&lt;</span></code> and <code class="display"><span class="extract-syntax">@&gt;</span></code> "brackets". (This notation
is given a name, written inside <span class="extract"><span class="extract-syntax">@&lt;</span></span> and <span class="extract"><span class="extract-syntax">@&gt;</span></span> "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-syntax">@&lt;Dramatic finale@&gt;</span></code>
item in the program. Instead, it expands any mention of <span class="extract"><span class="extract-syntax">@&lt;Dramatic finale@&gt;</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 <code class="display"><span class="extract-syntax">@&lt;Dramatic finale@&gt;</span></code>, but it would
would be quite free to define its own <span class="extract"><span class="extract-syntax">@&lt;Dramatic finale@&gt;</span></span>, but it would
not be able to see this one.
</p>
@ -308,12 +308,12 @@ named paragraph has, as its scope, just that paragraph. And this:
<span class="plain-syntax"> if (still_in_sieve[n])</span>
<span class="plain-syntax"> </span><span class="function-syntax">@&lt;Shake out multiples of n@&gt;</span><span class="plain-syntax">;</span>
</pre>
<p class="inwebparagraph">works safely because <code class="display"><span class="extract-syntax">@&lt;Shake out multiples of n@&gt;</span></code> is, thanks to being a
<p class="inwebparagraph">works safely because <span class="extract"><span class="extract-syntax">@&lt;Shake out multiples of n@&gt;</span></span> 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-syntax">@</span></code>. That is,
the paragraph then it's not necessary to type the initial <span class="extract"><span class="extract-syntax">@</span></span>. That is,
this:
</p>
@ -329,12 +329,12 @@ this:
<span class="plain-syntax"> </span><span class="function-syntax">@&lt;Prepare to exit@&gt; =</span>
</pre><p class="inwebparagraph"><a id="SP6"></a><b>&#167;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-syntax">#ifdef</span></code> clauses or the like.
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="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-syntax">^"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-syntax">SYMBOL</span></code> is defined.
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>
@ -347,13 +347,13 @@ For example, in a C-language web with the paragraph:
<span class="plain-syntax"> ...</span>
<span class="plain-syntax"> }</span>
</pre>
<p class="inwebparagraph">...the definition of <code class="display"><span class="extract-syntax">THREADS_AVAILABLE</span></code> and the function <code class="display"><span class="extract-syntax">start_threads</span></code>
would be made only inside a <code class="display"><span class="extract-syntax">#ifdef PLATFORM_WINDOWS</span></code> clause; the same would
happen for any typedefs or <code class="display"><span class="extract-syntax">#include</span></code>s made.
<p class="inwebparagraph">...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="inwebparagraph">Similarly, tagging a paragraph <code class="display"><span class="extract-syntax">^"ifndef-SYMBOL"</span></code> causes it to have effect
only if <code class="display"><span class="extract-syntax">SYMBOL</span></code> is undefined. A paragraph can have any number of such
<p class="inwebparagraph">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>
@ -390,9 +390,9 @@ set as such, running on into little indented paragraphs. Thus
</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-syntax">(...)</span></code> will be treated as a continuation of indented
<p class="inwebparagraph">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 <code class="display"><span class="extract-syntax">(-X)</span></code> will be treated as if it were <code class="display"><span class="extract-syntax">(X)</span></code>, but
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>
@ -401,7 +401,7 @@ indented one tab stop further in, like so:
</p>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>Text placed between vertical strokes will be set in a fixed-space, code
style font, <code class="display"><span class="extract-syntax">thus</span></code>. This paragraph appears in the web you are reading thus:
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">
@ -453,8 +453,8 @@ documentation reasons, is the answer. We can include this like so:
<span class="plain-syntax"> = (undisplayed text)</span>
</pre>
<p class="inwebparagraph">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 <code class="display"><span class="extract-syntax">undisplayed</span></code>
before <code class="display"><span class="extract-syntax">text</span></code> tells Inweb to do so less showily, on HTML weaves:
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">
@ -494,7 +494,7 @@ case, it knows the names of all those in your program.
</p>
<p class="inwebparagraph">Samples of code are, uniquely, allowed to end mid-way in a paragraph (unlike
real code): placing a <code class="display"><span class="extract-syntax">=</span></code> on the left margin allows the commentary to resume.
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>
@ -517,7 +517,7 @@ make them into links. For example:
end them with full stops or commas.
</p>
<p class="inwebparagraph">URLs will also be recognised in any text extract marked as <code class="display"><span class="extract-syntax">hyperlinked</span></code>.
<p class="inwebparagraph">URLs will also be recognised in any text extract marked as <span class="extract"><span class="extract-syntax">hyperlinked</span></span>.
For example,
</p>
@ -529,7 +529,7 @@ For example,
<pre class="displayed-code all-displayed-code">
<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="inwebparagraph"><a id="SP14"></a><b>&#167;14. Cross-references. </b>These are like links, but internal. These are normally written within <code class="display"><span class="extract-syntax">//</span></code>
</pre><p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. Cross-references. </b>These are like links, but 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>
@ -589,7 +589,7 @@ 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="inwebparagraph"><a id="SP17"></a><b>&#167;17. </b>Cross-references also work inside text extracts marked as <code class="display"><span class="extract-syntax">hyperlinked</span></code>.
<p class="inwebparagraph"><a id="SP17"></a><b>&#167;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">
@ -605,7 +605,7 @@ See <a href="M-mwiw.html" class="internal">Making Weaves into Websites</a>.
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph">This notation may be inconvenient if you need <code class="display"><span class="extract-syntax">//</span></code> for something else, but it
<p class="inwebparagraph">This notation may be inconvenient if you need <span class="extract"><span class="extract-syntax">//</span></span> for something else, but it
can be configured in the Contents page of a web, say like so:
</p>
@ -619,8 +619,8 @@ can be configured in the Contents page of a web, say like so:
<span class="element-syntax">Cross-References Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> Off</span>
</pre><p class="inwebparagraph"><a id="SP18"></a><b>&#167;18. 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 <code class="display"><span class="extract-syntax">Figures</span></code>: for instance,
the weaver would seek <code class="display"><span class="extract-syntax">Fig_2_3.pdf</span></code> at pathname <code class="display"><span class="extract-syntax">Figures/Fig_2_3.pdf</span></code>.
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="inwebparagraph">To embed an image, we write like so:
@ -750,7 +750,7 @@ slide lines were typed as:
<span class="plain-syntax"> = (carousel "Stage 2 - Developed tree" above)</span>
</pre>
<p class="inwebparagraph">and the like. By default, a caption overlaps slightly with the content; but
it can also be <code class="display"><span class="extract-syntax">above</span></code> or <code class="display"><span class="extract-syntax">below</span></code>. A slide can also have no caption at all:
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">
@ -772,8 +772,8 @@ cause videos to be embedded:
<center><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>
</center>
<p class="inwebparagraph">The YouTube ID number <code class="display"><span class="extract-syntax">GR3aImy7dWw</span></code> can be read from its Share URL, which in
this case was <code class="display"><span class="extract-syntax">https://youtu.be/GR3aImy7dWw</span></code>.
<p class="inwebparagraph">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="inwebparagraph">Similarly for Vimeo:
@ -813,15 +813,7 @@ this case was <code class="display"><span class="extract-syntax">https://youtu.b
arguably music has width and not height, but SoundCloud thinks otherwise).
</p>
<p class="inwebparagraph"><a id="SP22"></a><b>&#167;22. </b>It's easy to add services. These are all handled by using prototype code
for a suitable HTML <code class="display"><span class="extract-syntax">&lt;iframe&gt;</span></code>, and those prototypes are stored in the
<code class="display"><span class="extract-syntax">Embedding</span></code> subdirectory of the Inweb installation. But you can use your
own prototypes instead, by creating an <code class="display"><span class="extract-syntax">Embedding</span></code> subdirectory of your own
web; this overrides the ones built in. If your service is, say, <code class="display"><span class="extract-syntax">WebTubeo</span></code>,
then the file would be <code class="display"><span class="extract-syntax">W/Embedding/WebTubeo.html</span></code>.
</p>
<p class="inwebparagraph"><a id="SP23"></a><b>&#167;23. Mathematics notation. </b>Literate programming is a good technique to justify code which hangs on
<p class="inwebparagraph"><a id="SP22"></a><b>&#167;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>
@ -847,35 +839,20 @@ of the Riemann zeta function \(\zeta'(z)\) at \(z=2\).
<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="inwebparagraph">Mathematical formulae can be typed in TeX notation between dollar signs,
as usual for TeX formulae.
</p>
<p class="inwebparagraph">The rendering is done by default via the MathJax3 project, full details
of which can be found at: <a href="https://docs.mathjax.org/en/latest/index.html" class="external">https://docs.mathjax.org/en/latest/index.html</a>
</p>
<p class="inwebparagraph">Inweb in fact managed this by including a "plugin" with the HTML page you
are now reading: a plugin called <code class="display"><span class="extract-syntax">MathJax3</span></code>. Plugins are simply small
fragments of HTML added to the head of a page, and usually contain Javascript
code needed for special effects in it. To use a different renderer, simply
change the value of <code class="display"><span class="extract-syntax">TeX Mathematics Plugin</span></code> for your web (by default it is
set to <code class="display"><span class="extract-syntax">MathJax3</span></code>); or if you don't want to use Javascript at all, change
this to <code class="display"><span class="extract-syntax">None</span></code>, but then Inweb can really only make the grossest approximation
of what you would like to achieve.
</p>
<p class="inwebparagraph">In some webs, TeX notation is an unwanted nuisance. So this feature can be
deactivated entirely by writing the following in the Contents section of a web:
<p class="inwebparagraph">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">
<span class="plain-syntax"> </span><span class="element-syntax">TeX Mathematics Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> Off</span>
<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="inwebparagraph">(This is always <code class="display"><span class="extract-syntax">On</span></code>, the default, or <code class="display"><span class="extract-syntax">Off</span></code>.)
<p class="inwebparagraph">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="inwebparagraph"><a id="SP24"></a><b>&#167;24. 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
<p class="inwebparagraph"><a id="SP23"></a><b>&#167;23. 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>
@ -883,7 +860,7 @@ references.<sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup>
University Press, 1999).
<a href="#fnref:1" title="return to text"> &#x21A9;</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 &amp; Mathematics with Applications, 2, 137-39 (1976).
<a href="#fnref:2" title="return to text"> &#x21A9;</a></p></li></ul><p class="inwebparagraph"><a id="SP25"></a><b>&#167;25. </b>The content of that sentence was typed as follows:
<a href="#fnref:2" title="return to text"> &#x21A9;</a></p></li></ul><p class="inwebparagraph"><a id="SP24"></a><b>&#167;24. </b>The content of that sentence was typed as follows:
</p>
<pre class="displayed-code all-displayed-code">
@ -905,21 +882,7 @@ have seen clickable footnote blobs, which reveal the text. If Javascript is
off, there's a more conventionally textual presentation.
</p>
<p class="inwebparagraph">These blob-footnotes are fine for snarky asides or quick references, but long
discursive notes need more space, so if you intend to use those then you
should probably turn this rendering off altogether:
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> </span><span class="element-syntax">Footnotes Plugin</span><span class="plain-syntax">:</span><span class="string-syntax"> None</span>
</pre>
<p class="inwebparagraph">Footnotes are otherwise rendered by the <code class="display"><span class="extract-syntax">Bigfoot</span></code> plugin, which is the default
value of this; its big feet unfortunately tread on the <code class="display"><span class="extract-syntax">MathJax3</span></code> plugin, so
right now it's not possible to have mathematics in a footnote when <code class="display"><span class="extract-syntax">Bigfoot</span></code>
is in use.
</p>
<p class="inwebparagraph"><a id="SP26"></a><b>&#167;26. </b>Once again, notation may be an issue, and so it's controllable. By default,
<p class="inwebparagraph">Once again, notation may be an issue, and so it's controllable. By default,
we have:
</p>

20
docs/inweb/M-iti.html
View file

@ -70,14 +70,14 @@ an ebook then you're looking at the woven form.
</p>
<p class="inwebparagraph">While small webs can be written as single files, Inweb is not a small web,
so it occupies a directory called <code class="display"><span class="extract-syntax">inweb</span></code>. This is what you see if you pull
so it occupies a directory called <span class="extract"><span class="extract-syntax">inweb</span></span>. This is what you see if you pull
the project from GitHub, for example.
</p>
<p class="inwebparagraph">There is clearly a circularity here. To compile Inweb, you must first run
Inweb to tangle it. But if you already had Inweb, you wouldn't need to compile
it. Here's what to do. From a command-line prompt, set the current working
directory to be the one in which Inweb is stored - that is, not the <code class="display"><span class="extract-syntax">inweb</span></code>
directory to be the one in which Inweb is stored - that is, not the <span class="extract"><span class="extract-syntax">inweb</span></span>
directory itself, but its parent. Then type one of the following:
</p>
@ -110,7 +110,7 @@ the default macos unless you need to build for an old version of MacOS.
</pre>
<p class="inwebparagraph">(All that happened, in fact, was that a platform-specific file of make
settings &mdash; what compilers to use, what options, and so on &mdash; was copied
over to become the file <code class="display"><span class="ConsoleText-extract-syntax">inweb/platform-settings.mk</span></code>. This is a file which
over to become the file <span class="extract"><span class="ConsoleText-extract-syntax">inweb/platform-settings.mk</span></span>. This is a file which
is necessary for Inweb to be fully used, but which is intentionally not
included in the Git repository for Inweb, in order to oblige users to choose
a platform before doing anything else.) Anyway, next do as instructed:
@ -121,7 +121,7 @@ a platform before doing anything else.) Anyway, next do as instructed:
</pre>
<p class="inwebparagraph">With that done, make should go on to compile the Inweb executable, leaving
you with a working copy of the software. You need never run that
platform-specific command, or make as <code class="display"><span class="ConsoleText-extract-syntax">initial</span></code>, again: you can simply:
platform-specific command, or make as <span class="extract"><span class="ConsoleText-extract-syntax">initial</span></span>, again: you can simply:
</p>
<pre class="ConsoleText-displayed-code all-displayed-code">
@ -137,7 +137,7 @@ platform-specific command, or make as <code class="display"><span class="Console
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inweb/Tangled/inweb</span><span class="ConsoleText-identifier-syntax"> -help</span>
</pre>
<p class="inwebparagraph">That location is where the compiled tool ended up. Users of, for example,
the <code class="display"><span class="ConsoleText-extract-syntax">bash</span></code> shell may want to
the <span class="extract"><span class="ConsoleText-extract-syntax">bash</span></span> shell may want to
</p>
<pre class="ConsoleText-displayed-code all-displayed-code">
@ -152,18 +152,18 @@ system. There is no completely foolproof, cross-platform way to know this
decides by the following set of rules:
</p>
<ul class="items"><li>(a) If the user, at the command line, specified <code class="display"><span class="ConsoleText-extract-syntax">-at P</span></code>, for some path
<code class="display"><span class="ConsoleText-extract-syntax">P</span></code>, then we use that.
<ul class="items"><li>(a) If the user, at the command line, specified <span class="extract"><span class="ConsoleText-extract-syntax">-at P</span></span>, for some path
<span class="extract"><span class="ConsoleText-extract-syntax">P</span></span>, then we use that.
</li><li>(b) Otherwise, if the host operating system can indeed tell us where the
executable is, we use that. This is currently implemented only on MacOS,
Windows and Linux.
</li><li>(c) Otherwise, if the environment variable <code class="display"><span class="ConsoleText-extract-syntax">$INWEB_PATH</span></code> exists and is
</li><li>(c) Otherwise, if the environment variable <span class="extract"><span class="ConsoleText-extract-syntax">$INWEB_PATH</span></span> exists and is
non-empty, we use that.
</li><li>(d) And if all else fails, we assume that the location is <code class="display"><span class="ConsoleText-extract-syntax">inweb</span></code>, with
</li><li>(d) And if all else fails, we assume that the location is <span class="extract"><span class="ConsoleText-extract-syntax">inweb</span></span>, with
respect to the current working directory.
</li></ul>
<p class="inwebparagraph">If you're not sure what Inweb has decided and suspect it may be wrong,
running Inweb with the <code class="display"><span class="ConsoleText-extract-syntax">-verbose</span></code> switch will cause it to print its belief
running Inweb with the <span class="extract"><span class="ConsoleText-extract-syntax">-verbose</span></span> switch will cause it to print its belief
about its location as it starts up.
</p>

101
docs/inweb/M-mwiw.html
View file

@ -38,17 +38,17 @@
<!--Weave of 'Making Weaves into Websites' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</a></li><li><b>Making Weaves into Websites</b></li></ul><p class="purpose">How to present one or more weaves on a shared website, for example using GitHub Pages.</p>
<ul class="toc"><li><a href="M-mwiw.html#SP1">&#167;1. GitHub Pages</a></li><li><a href="M-mwiw.html#SP2">&#167;2. Colonies</a></li><li><a href="M-mwiw.html#SP6">&#167;6. The navigation sidebar</a></li><li><a href="M-mwiw.html#SP9">&#167;9. The trail of breadcrumbs</a></li></ul><hr class="tocbar">
<ul class="toc"><li><a href="M-mwiw.html#SP1">&#167;1. GitHub Pages</a></li><li><a href="M-mwiw.html#SP2">&#167;2. Colonies</a></li><li><a href="M-mwiw.html#SP7">&#167;7. The navigation sidebar</a></li><li><a href="M-mwiw.html#SP10">&#167;10. The trail of breadcrumbs</a></li><li><a href="M-mwiw.html#SP11">&#167;11. Adding custom HTML, CSS and such</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. GitHub Pages. </b>If a project is hosted at GitHub, then the GitHub Pages service is the ideal
place to serve a woven copy of the project to the world: the <code class="display"><span class="extract-syntax">docs</span></code> subdirectory
place to serve a woven copy of the project to the world: the <span class="extract"><span class="extract-syntax">docs</span></span> subdirectory
of a repository is simply served as a website, once this is enabled from the
owner's Github control panel.
</p>
<p class="inwebparagraph">First, the simple case: our repository is a single web, called <code class="display"><span class="extract-syntax">example</span></code>.
<p class="inwebparagraph">First, the simple case: our repository is a single web, called <span class="extract"><span class="extract-syntax">example</span></span>.
We suppose that the current working directory is one up from this, and contains
the installation of <code class="display"><span class="extract-syntax">inweb</span></code> as well as <code class="display"><span class="extract-syntax">example</span></code>. Then:
the installation of <span class="extract"><span class="extract-syntax">inweb</span></span> as well as <span class="extract"><span class="extract-syntax">example</span></span>. Then:
</p>
<pre class="ConsoleText-displayed-code all-displayed-code">
@ -56,7 +56,7 @@ the installation of <code class="display"><span class="extract-syntax">inweb</sp
<span class="ConsoleText-plain-syntax"> inweb example</span>
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inweb/Tangled/inweb</span><span class="ConsoleText-plain-syntax"> example</span><span class="ConsoleText-identifier-syntax"> -weave-as</span><span class="ConsoleText-plain-syntax"> GitHubPages</span><span class="ConsoleText-identifier-syntax"> -weave-into</span><span class="ConsoleText-plain-syntax"> example/docs</span>
</pre>
<p class="inwebparagraph">will do the trick. (<code class="display"><span class="ConsoleText-extract-syntax">GitHubPages</span></code> is a pattern refining the default <code class="display"><span class="ConsoleText-extract-syntax">HTML</span></code> one.)
<p class="inwebparagraph">will do the trick. (<span class="extract"><span class="ConsoleText-extract-syntax">GitHubPages</span></span> is a pattern refining the default <span class="extract"><span class="ConsoleText-extract-syntax">HTML</span></span> one.)
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Colonies. </b>A collection of webs gathered in one place is, for want of a better word,
@ -66,13 +66,13 @@ webs which are collectively woven.)
<p class="inwebparagraph">Inweb provides support for colonies, and this enables us to manage the more
complicated case where there are multiple webs in a repository, but which need
to share the same <code class="display"><span class="ConsoleText-extract-syntax">docs</span></code> area. Now the problem to tackle is that we have two
or more webs in our <code class="display"><span class="ConsoleText-extract-syntax">example</span></code> repository, one at <code class="display"><span class="ConsoleText-extract-syntax">example/aleph</span></code>, the other
at <code class="display"><span class="ConsoleText-extract-syntax">example/beth</span></code>.
to share the same <span class="extract"><span class="ConsoleText-extract-syntax">docs</span></span> area. Now the problem to tackle is that we have two
or more webs in our <span class="extract"><span class="ConsoleText-extract-syntax">example</span></span> repository, one at <span class="extract"><span class="ConsoleText-extract-syntax">example/aleph</span></span>, the other
at <span class="extract"><span class="ConsoleText-extract-syntax">example/beth</span></span>.
</p>
<p class="inwebparagraph">The first thing to do is to write a colony file &mdash; we could put this anywhere
in the repository, but let's say at <code class="display"><span class="ConsoleText-extract-syntax">example/colony.txt</span></code>:
in the repository, but let's say at <span class="extract"><span class="ConsoleText-extract-syntax">example/colony.txt</span></span>:
</p>
<pre class="ConsoleText-displayed-code all-displayed-code">
@ -93,9 +93,9 @@ now write, for example,
<pre class="ConsoleText-displayed-code all-displayed-code">
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inweb/Tangled/inweb</span><span class="ConsoleText-plain-syntax"> example/beth</span><span class="ConsoleText-identifier-syntax"> -weave -weave-into</span><span class="ConsoleText-plain-syntax"> example/docs/beth</span><span class="ConsoleText-identifier-syntax"> -weave-as</span><span class="ConsoleText-plain-syntax"> GitHubPages</span>
</pre>
<p class="inwebparagraph">The idea is that <code class="display"><span class="ConsoleText-extract-syntax">-member M</span></code> chooses <code class="display"><span class="ConsoleText-extract-syntax">M</span></code> as the current web, and automatically
sets its default settings: <code class="display"><span class="ConsoleText-extract-syntax">-weave-to</span></code>, <code class="display"><span class="ConsoleText-extract-syntax">-weave-as</span></code>, <code class="display"><span class="ConsoleText-extract-syntax">-navigation</span></code> and
<code class="display"><span class="ConsoleText-extract-syntax">-breadcrumb</span></code> are all handled like this.
<p class="inwebparagraph">The idea is that <span class="extract"><span class="ConsoleText-extract-syntax">-member M</span></span> chooses <span class="extract"><span class="ConsoleText-extract-syntax">M</span></span> as the current web, and automatically
sets its default settings: <span class="extract"><span class="ConsoleText-extract-syntax">-weave-to</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">-weave-as</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">-navigation</span></span> and
<span class="extract"><span class="ConsoleText-extract-syntax">-breadcrumb</span></span> are all handled like this.
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>These pathnames are taken relative to the current working directory of
@ -107,13 +107,13 @@ file needs to say:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> home: inweb/docs</span>
</pre>
<p class="inwebparagraph">This overrides the default setting (just <code class="display"><span class="extract-syntax">docs</span></code>), and is the path to the
<p class="inwebparagraph">This overrides the default setting (just <span class="extract"><span class="extract-syntax">docs</span></span>), and is the path to the
home page of the Github Docs area for the repository.
</p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>The use of a colony also enables cross-references from the weave of one
web to the weave of another, even when they are independent programs. For
example, a section of code in <code class="display"><span class="extract-syntax">beth</span></code> could say:
example, a section of code in <span class="extract"><span class="extract-syntax">beth</span></span> could say:
</p>
<pre class="displayed-code all-displayed-code">
@ -121,7 +121,7 @@ example, a section of code in <code class="display"><span class="extract-syntax"
<span class="plain-syntax"> for us, so we'll just proceed. (See //aleph: Error Recovery//.)</span>
</pre>
<p class="inwebparagraph">and these links would both work. Without the use of a colony file, neither
one could be recognised, because Inweb wouldn't know what <code class="display"><span class="extract-syntax">aleph</span></code> even was.
one could be recognised, because Inweb wouldn't know what <span class="extract"><span class="extract-syntax">aleph</span></span> even was.
To demonstrate that right here, see <a href="../goldbach/S-tsoe.html" class="internal">The Sieve of Eratosthenes (in goldbach)</a>.
That last sentence was typed as:
</p>
@ -165,46 +165,60 @@ Each one gives (a) a short name, (b) a location relative to the current
working directory, and (c) a similar location for its woven collection of
files. The file can also specify navigation and breadcrumbs material, and
the pattern; each of these applies to each subsequent declaration until the
setting in question changes again. (Setting to <code class="display"><span class="extract-syntax">none</span></code> removes them.)
setting in question changes again. (Setting to <span class="extract"><span class="extract-syntax">none</span></span> removes them.)
</p>
<p class="inwebparagraph">Also notable here is that the colony contains a single-page web called
<code class="display"><span class="extract-syntax">index.inweb</span></code>. (You can see that it's a single-page web, rather than something
more substantial, because the location ends <code class="display"><span class="extract-syntax">.inweb</span></code> rather than being a
directory name.) The point of this web is that it weaves to the <code class="display"><span class="extract-syntax">index.html</span></code>
<span class="extract"><span class="extract-syntax">index.inweb</span></span>. (You can see that it's a single-page web, rather than something
more substantial, because the location ends <span class="extract"><span class="extract-syntax">.inweb</span></span> rather than being a
directory name.) The point of this web is that it weaves to the <span class="extract"><span class="extract-syntax">index.html</span></span>
home page; it's referred to in links as being the "overview", because that's
its name as a web.
</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. The navigation sidebar. </b>When assembling large numbers of woven websites together, as is needed for
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>The command <span class="extract"><span class="extract-syntax">assets X</span></span> tells Inweb to place "assets" such as images, CSS and
JavaScript files which are needed by plugins (see <a href="M-awwp.html" class="internal">Advanced Weaving with Patterns</a>)
into the directory <span class="extract"><span class="extract-syntax">X</span></span>. In practice, this avoids a great deal of duplication:
if there are 30 webs in the colony, there's no need for each to have its own
copy of the same CSS files for the basic page makeup. (But that is what will
indeed happen if the <span class="extract"><span class="extract-syntax">assets</span></span> command is not used.)
</p>
<p class="inwebparagraph">Another convenience is <span class="extract"><span class="extract-syntax">patterns X</span></span>, which tells X that some unusual weave
patterns can be found in directory <span class="extract"><span class="extract-syntax">X</span></span>. That's useful if multiple webs in
the colony need to use the same pattern, and the pattern isn't one which is
built in the Inweb.
</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. The navigation sidebar. </b>When assembling large numbers of woven websites together, as is needed for
example by the main Inform repository's GitHub pages, we need to navigate
externally as well as internally: that is, the page for one tool will need
a way to link to pages for other tools.
</p>
<p class="inwebparagraph">This is why the <code class="display"><span class="extract-syntax">GitHubPages</span></code> pattern has a navigation sidebar, to the left
<p class="inwebparagraph">This is why the <span class="extract"><span class="extract-syntax">GitHubPages</span></span> pattern has a navigation sidebar, to the left
of the main part of each page. The template file contains a special expansion
written <code class="display"><span class="extract-syntax">[[Navigation]]</span></code>, and this expands to the HTML for a column of links.
written <span class="extract"><span class="extract-syntax">[[Navigation]]</span></span>, and this expands to the HTML for a column of links.
</p>
<p class="inwebparagraph">The pattern also has a row of breadcrumbs along the top, for navigation within
the current web.
</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b>By default, Inweb looks for a file called <code class="display"><span class="extract-syntax">nav.html</span></code> in two directories: the
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>By default, Inweb looks for a file called <span class="extract"><span class="extract-syntax">nav.html</span></span> in two directories: the
one above the destination, and the destination. If both exist, they are both
used. If neither exists, the expansion is empty, but no error is produced.
</p>
<p class="inwebparagraph">However, this can be overridden at the command line, with <code class="display"><span class="extract-syntax">-navigation N</span></code>,
where <code class="display"><span class="extract-syntax">N</span></code> is the filename for a suitable fragment of navigation HTML, and
<p class="inwebparagraph">However, this can be overridden at the command line, with <span class="extract"><span class="extract-syntax">-navigation N</span></span>,
where <span class="extract"><span class="extract-syntax">N</span></span> is the filename for a suitable fragment of navigation HTML, and
it can also be preset in the Colony file (see above).
</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b>Inweb in fact makes it easy to write such navigation files, providing
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>Inweb in fact makes it easy to write such navigation files, providing
commands which mean that little HTML need be written at all. This is the
one which generates the sidebar visible to the left of the pages on the
Inweb <code class="display"><span class="extract-syntax">docs</span></code> site:
Inweb <span class="extract"><span class="extract-syntax">docs</span></span> site:
</p>
<pre class="displayed-code all-displayed-code">
@ -226,14 +240,14 @@ Inweb <code class="display"><span class="extract-syntax">docs</span></code> site
<span class="plain-syntax">[[Item "intest"]]</span>
</pre>
<p class="inwebparagraph">As this shows, there's some HTML for the top left corner area, and then
a list of items and submenus. <code class="display"><span class="extract-syntax">[[Link "overview"]]</span></code> opens a link to the
colony item called <code class="display"><span class="extract-syntax">overview</span></code>; <code class="display"><span class="extract-syntax">[[URL "inweb"]]</span></code> writes a minimal-length
relative URL to reach the named directory, and <code class="display"><span class="extract-syntax">[[Docs]]</span></code> to the home page
of the Github Docs area for the repository. <code class="display"><span class="extract-syntax">[[Menu "External"]]</span></code> begins
a submenu among the items. <code class="display"><span class="extract-syntax">[[Item "X"]]</span></code> makes a menu item whose title is
<code class="display"><span class="extract-syntax">X</span></code> and which links to the colony item called <code class="display"><span class="extract-syntax">X</span></code>; <code class="display"><span class="extract-syntax">[[Item "Y" -&gt; Z]]</span></code> is
more general, and makes the text <code class="display"><span class="extract-syntax">Y</span></code> point to either an external web page,
recognised by beginning with <code class="display"><span class="extract-syntax">http</span></code>, or else a web cross-reference. Thus:
a list of items and submenus. <span class="extract"><span class="extract-syntax">[[Link "overview"]]</span></span> opens a link to the
colony item called <span class="extract"><span class="extract-syntax">overview</span></span>; <span class="extract"><span class="extract-syntax">[[URL "inweb"]]</span></span> writes a minimal-length
relative URL to reach the named directory, and <span class="extract"><span class="extract-syntax">[[Docs]]</span></span> to the home page
of the Github Docs area for the repository. <span class="extract"><span class="extract-syntax">[[Menu "External"]]</span></span> begins
a submenu among the items. <span class="extract"><span class="extract-syntax">[[Item "X"]]</span></span> makes a menu item whose title is
<span class="extract"><span class="extract-syntax">X</span></span> and which links to the colony item called <span class="extract"><span class="extract-syntax">X</span></span>; <span class="extract"><span class="extract-syntax">[[Item "Y" -&gt; Z]]</span></span> is
more general, and makes the text <span class="extract"><span class="extract-syntax">Y</span></span> point to either an external web page,
recognised by beginning with <span class="extract"><span class="extract-syntax">http</span></span>, or else a web cross-reference. Thus:
</p>
<pre class="displayed-code all-displayed-code">
@ -250,12 +264,12 @@ example:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> [[Item "&lt;github.png&gt; github" -&gt; https://github.com/ganelson/intest]]</span>
</pre>
<p class="inwebparagraph">This icon should be in the <code class="display"><span class="extract-syntax">docs</span></code> home of the repository. Note that the
<code class="display"><span class="extract-syntax">GithubPages</span></code> pattern automatically includes the <code class="display"><span class="extract-syntax">github.png</span></code> icon, so
<p class="inwebparagraph">This icon should be in the <span class="extract"><span class="extract-syntax">docs</span></span> home of the repository. Note that the
<span class="extract"><span class="extract-syntax">GithubPages</span></span> pattern automatically includes the <span class="extract"><span class="extract-syntax">github.png</span></span> icon, so
that one's guaranteed to be present.
</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. The trail of breadcrumbs. </b>Inweb automatically adds web, chapter and section titles to the trail of
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. The trail of breadcrumbs. </b>Inweb automatically adds web, chapter and section titles to the trail of
breadcrumbs above each page: for example,
</p>
@ -269,15 +283,15 @@ crumbs to the left. Suppose we want:
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax">Home &gt; Beth &gt; Chapter 4 &gt; File Organisation</span>
</pre>
<p class="inwebparagraph">where Home is a link to <code class="display"><span class="extract-syntax">example/docs/index.html</span></code>. One way is to run Inweb
with <code class="display"><span class="extract-syntax">-breadcrumb 'Home:index.html'</span></code>; another is to add this to the Colony
<p class="inwebparagraph">where Home is a link to <span class="extract"><span class="extract-syntax">example/docs/index.html</span></span>. One way is to run Inweb
with <span class="extract"><span class="extract-syntax">-breadcrumb 'Home:index.html'</span></span>; another is to add this to the Colony
file, as
</p>
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> breadcrumbs: "Home: index.html"</span>
</pre>
<p class="inwebparagraph">We can add more than one, by, e.g., <code class="display"><span class="extract-syntax">-breadcrumb 'Home:index.html' -breadcrumb 'Webs: webs.html'</span></code>.
<p class="inwebparagraph">We can add more than one, by, e.g., <span class="extract"><span class="extract-syntax">-breadcrumb 'Home:index.html' -breadcrumb 'Webs: webs.html'</span></span>.
</p>
<pre class="displayed-code all-displayed-code">
@ -289,7 +303,10 @@ file, as
<pre class="displayed-code all-displayed-code">
<span class="plain-syntax"> breadcrumbs: "Overview: //overview//"</span>
</pre>
<p class="inwebparagraph">makes a link to the web/module called <code class="display"><span class="extract-syntax">overview</span></code> in the colony file.
<p class="inwebparagraph">makes a link to the web/module called <span class="extract"><span class="extract-syntax">overview</span></span> in the colony file.
</p>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. Adding custom HTML, CSS and such. </b>This is done by creating a new pattern: see <a href="M-awwp.html" class="internal">Advanced Weaving with Patterns</a>.
</p>
<hr class="tocbar">

4
docs/inweb/M-rc.html
View file

@ -37,7 +37,7 @@
<!--Weave of 'Reference Card' generated by Inweb-->
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</a></li><li><b>Reference Card</b></li></ul><p class="purpose">The current help information as it would be printed at the command line.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>Running Inweb with <code class="display"><span class="extract-syntax">-help</span></code> currently produces the following summary:
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>Running Inweb with <span class="extract"><span class="extract-syntax">-help</span></span> currently produces the following summary:
</p>
<pre class="undisplayed-code all-displayed-code">
@ -105,7 +105,7 @@
<span class="plain-syntax">-help print this help information</span>
<span class="plain-syntax">-log X write the debugging log to include diagnostics on X</span>
<span class="plain-syntax">-version print out version number</span>
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Running Inweb with <code class="display"><span class="extract-syntax">-show-languages</span></code> currently produces the following list
</pre><p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Running Inweb with <span class="extract"><span class="extract-syntax">-show-languages</span></span> currently produces the following list
of programming languages for which support is provided in the standard
distribution:
</p>

Some files were not shown because too many files have changed in this diff Show more