diff --git a/Chapter 1/Patterns.w b/Chapter 1/Patterns.w index a7a82af..70f3e85 100644 --- a/Chapter 1/Patterns.w +++ b/Chapter 1/Patterns.w @@ -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; @ = 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+)")) @; - if (Regexp::match(&mr, line, L" *(%c+?) = (%c+)")) @; - if (Regexp::match(&mr, line, L" *embed css *")) @; - if (Regexp::match(&mr, line, L" *hierarchical *")) @; - if (Regexp::match(&mr, line, L" *plugin (%c+)")) @; - if (Regexp::match(&mr, line, L" *use (%c+)")) @; - if (Regexp::match(&mr, line, L" *use-up (%c+)")) @; - if (Regexp::match(&mr, line, L" *%C%c*")) - Errors::in_text_file("unrecognised pattern command", tfp); - Regexp::dispose_of(&mr); -} - -@ = - wp->based_on = Patterns::find(wp->patterned_for, mr.exp[0]); - Regexp::dispose_of(&mr); - return; - -@ = - 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; - -@ = - wp->embed_CSS = TRUE; - Regexp::dispose_of(&mr); - return; - -@ = - wp->hierarchical = TRUE; - Regexp::dispose_of(&mr); - return; - -@ "Plugins" here refer to //Weave Plugins//. - -@ = - 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. - -@ = - text_stream *leafname = Str::duplicate(mr.exp[0]); - ADD_TO_LINKED_LIST(leafname, text_stream, wp->payloads); - Regexp::dispose_of(&mr); - return; - -@ = - 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) { diff --git a/Chapter 1/Program Control.w b/Chapter 1/Program Control.w index 02474dc..249ca3d 100644 --- a/Chapter 1/Program Control.w +++ b/Chapter 1/Program Control.w @@ -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, diff --git a/Chapter 1/The Swarm.w b/Chapter 1/The Swarm.w index 98b447c..ab17e02 100644 --- a/Chapter 1/The Swarm.w +++ b/Chapter 1/The Swarm.w @@ -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); } diff --git a/Chapter 3/The Indexer.w b/Chapter 3/The Indexer.w index 150dab9..bae63b0 100644 --- a/Chapter 3/The Indexer.w +++ b/Chapter 3/The Indexer.w @@ -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" *%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); - @; - 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); + @; + 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) @; } else if (Regexp::match(&mr2, command, L"Navigation")) { if (include) @; } 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); -@ = - 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); - } - @ = 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) @; - if ((ies->nav_pattern->embed_CSS) && - (Regexp::match(&mr, tl, L" *%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("\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. = diff --git a/Chapter 5/HTML Formats.w b/Chapter 5/HTML Formats.w index 814066a..f352fe2 100644 --- a/Chapter 5/HTML Formats.w +++ b/Chapter 5/HTML Formats.w @@ -520,18 +520,16 @@ that service uses to identify the video/audio in question. @ = 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("%S", C->cue_text, C->cue_text, C->cue_text); @ = 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("

  • ", 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); @ = - 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; @ = @@ -596,9 +594,8 @@ that service uses to identify the video/audio in question. @ = 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); diff --git a/Chapter 5/TeX Format.w b/Chapter 5/TeX Format.w index 49c93c0..d1822e9 100644 --- a/Chapter 5/TeX Format.w +++ b/Chapter 5/TeX Format.w @@ -245,11 +245,7 @@ to a given width, into the text at the current position. if (C->in_code) WRITE("}"); @ = - 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); diff --git a/Chapter 5/Weave Plugins.w b/Chapter 5/Weave Plugins.w index 83ab987..64e5820 100644 --- a/Chapter 5/Weave Plugins.w +++ b/Chapter 5/Weave Plugins.w @@ -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); + @; } } 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("\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("\n", url); DISCARD_TEXT(url); + @; + } else { + @; } + } else { + @; } - 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); } +@ = + 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("\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("\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("\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); + } + } +} diff --git a/Manual/Advanced Weaving with Patterns.w b/Manual/Advanced Weaving with Patterns.w index 331095e..f740094 100644 --- a/Manual/Advanced Weaving with Patterns.w +++ b/Manual/Advanced Weaving with Patterns.w @@ -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) + + + + [[Booklet Title]] + [[Plugins]] + + +[[Code]] + + += +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 diff --git a/Manual/How to Write a Web.w b/Manual/How to Write a Web.w index 48d0079..0f56e40 100644 --- a/Manual/How to Write a Web.w +++ b/Manual/How to Write a Web.w @@ -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 | -

    The YouTube ID number GR3aImy7dWw can be read from its Share URL, which in -this case was https://youtu.be/GR3aImy7dWw. +

    The YouTube ID number GR3aImy7dWw can be read from its Share URL, which in +this case was https://youtu.be/GR3aImy7dWw.

    Similarly for Vimeo: @@ -813,15 +813,7 @@ this case was https://youtu.b arguably music has width and not height, but SoundCloud thinks otherwise).

    -

    §22. 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. -

    - -

    §23. Mathematics notation. Literate programming is a good technique to justify code which hangs on +

    §22. 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 be explained carefully. Formulae or equations are a real convenience for that.

    @@ -847,35 +839,20 @@ of the Riemann zeta function \(\zeta'(z)\) at \(z=2\). 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: 

    -    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.

    -

    §24. Footnotes. Not everyone likes footnotes,1 but sometimes they're a tidy way to make +

    §23. Footnotes. Not everyone likes footnotes,1 but sometimes they're a tidy way to make references.2

    @@ -883,7 +860,7 @@ references.2 University Press, 1999). ↩

  • 2 For example, to cite Donald Knuth, "Evaluation of Porter's constant", Computers & Mathematics with Applications, 2, 137-39 (1976). - ↩

    • §25. The content of that sentence was typed as follows: + ↩

    §24. The content of that sentence was typed as follows: 

    @@ -905,21 +882,7 @@ 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:
-
    
-
-
    -    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.
-
    
-
-
    §26.  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:
 
    
 
diff --git a/docs/inweb/M-iti.html b/docs/inweb/M-iti.html
index b8958ce..111ec77 100644
--- a/docs/inweb/M-iti.html
+++ b/docs/inweb/M-iti.html
@@ -70,14 +70,14 @@ an ebook then you're looking at the woven form.
 
    
 
 
    While small webs can be written as single files, Inweb is not a small web,
-so it occupies a directory called inweb. This is what you see if you pull
+so it occupies a directory called inweb. This is what you see if you pull
 the project from GitHub, for example.
 
    
 
 
    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 inweb
+directory to be the one in which Inweb is stored - that is, not the inweb
 directory itself, but its parent. Then type one of the following:
 
    
 
@@ -110,7 +110,7 @@ the default macos unless you need to build for an old version of MacOS.

    (All that happened, in fact, was that a platform-specific file of make settings — what compilers to use, what options, and so on — was copied -over to become the file inweb/platform-settings.mk. This is a file which +over to become the file inweb/platform-settings.mk. 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:

    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 initial, again: you can simply: +platform-specific command, or make as initial, again: you can simply: 

    @@ -137,7 +137,7 @@ platform-specific command, or make as     $ inweb/Tangled/inweb -help

    That location is where the compiled tool ended up. Users of, for example, -the bash shell may want to +the bash shell may want to 

    @@ -152,18 +152,18 @@ system. There is no completely foolproof, cross-platform way to know this
 decides by the following set of rules:
 
    
 
-
    • (a) If the user, at the command line, specified -at P, for some path
-P, then we use that.
+
      • (a) If the user, at the command line, specified -at P, for some path
+P, then we use that.
 
      • (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.
-
      • (c) Otherwise, if the environment variable $INWEB_PATH exists and is
+
      • (c) Otherwise, if the environment variable $INWEB_PATH exists and is
 non-empty, we use that.
-
      • (d) And if all else fails, we assume that the location is inweb, with
+
      • (d) And if all else fails, we assume that the location is inweb, with
 respect to the current working directory.
 
      
 
      If you're not sure what Inweb has decided and suspect it may be wrong,
-running Inweb with the -verbose switch will cause it to print its belief
+running Inweb with the -verbose switch will cause it to print its belief
 about its location as it starts up.
 
      
 
diff --git a/docs/inweb/M-mwiw.html b/docs/inweb/M-mwiw.html
index 9b35b5b..6fdafb3 100644
--- a/docs/inweb/M-mwiw.html
+++ b/docs/inweb/M-mwiw.html
@@ -38,17 +38,17 @@
 
 
      How to present one or more weaves on a shared website, for example using GitHub Pages.
      
 
-
      
+
      
 
 
      §1. GitHub Pages. 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 docs subdirectory
+place to serve a woven copy of the project to the world: the docs subdirectory
 of a repository is simply served as a website, once this is enabled from the
 owner's Github control panel.
 
      
 
-
      First, the simple case: our repository is a single web, called example.
+
      First, the simple case: our repository is a single web, called example.
 We suppose that the current working directory is one up from this, and contains
-the installation of inweb as well as example. Then:
+the installation of inweb as well as example. Then:
 
      
 
 
      @@ -56,7 +56,7 @@ the installation of inweb    inweb   example
     $ inweb/Tangled/inweb example -weave-as GitHubPages -weave-into example/docs
 
      
-
      will do the trick. (GitHubPages is a pattern refining the default HTML one.)
+
      will do the trick. (GitHubPages is a pattern refining the default HTML one.)
 
      
 
 
      §2. Colonies. A collection of webs gathered in one place is, for want of a better word,
@@ -66,13 +66,13 @@ webs which are collectively woven.)
 
 
      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 docs area. Now the problem to tackle is that we have two
-or more webs in our example repository, one at example/aleph, the other
-at example/beth.
+to share the same docs area. Now the problem to tackle is that we have two
+or more webs in our example repository, one at example/aleph, the other
+at example/beth.
 
      
 
 
      The first thing to do is to write a colony file — we could put this anywhere
-in the repository, but let's say at example/colony.txt:
+in the repository, but let's say at example/colony.txt:
 
      
 
 
      @@ -93,9 +93,9 @@ now write, for example,
 
           $ inweb/Tangled/inweb example/beth -weave -weave-into example/docs/beth -weave-as GitHubPages
 
      
-
      The idea is that -member M chooses M as the current web, and automatically
-sets its default settings: -weave-to, -weave-as, -navigation and
--breadcrumb are all handled like this.
+
      The idea is that -member M chooses M as the current web, and automatically
+sets its default settings: -weave-to, -weave-as, -navigation and
+-breadcrumb are all handled like this.
 
      
 
 
      §3.  These pathnames are taken relative to the current working directory of
@@ -107,13 +107,13 @@ file needs to say:
 
           home: inweb/docs
 
      
-
      This overrides the default setting (just docs), and is the path to the
+
      This overrides the default setting (just docs), and is the path to the
 home page of the Github Docs area for the repository.
 
      
 
 
      §4.  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 beth could say:
+example, a section of code in beth could say:
 
      
 
 
      @@ -121,7 +121,7 @@ example, a section of code in     for us, so we'll just proceed. (See //aleph: Error Recovery//.)
 
      
 
      and these links would both work. Without the use of a colony file, neither
-one could be recognised, because Inweb wouldn't know what aleph even was.
+one could be recognised, because Inweb wouldn't know what aleph even was.
 To demonstrate that right here, see The Sieve of Eratosthenes (in goldbach).
 That last sentence was typed as:
 
      
@@ -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 none removes them.)
+setting in question changes again. (Setting to none removes them.)
 
      
 
 
      Also notable here is that the colony contains a single-page web called
-index.inweb. (You can see that it's a single-page web, rather than something
-more substantial, because the location ends .inweb rather than being a
-directory name.) The point of this web is that it weaves to the index.html
+index.inweb. (You can see that it's a single-page web, rather than something
+more substantial, because the location ends .inweb rather than being a
+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.
 
      
 
-
      §6. The navigation sidebar. When assembling large numbers of woven websites together, as is needed for
+
      §6.  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.
+
      
+
+
      §7. 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
 externally as well as internally: that is, the page for one tool will need
 a way to link to pages for other tools.
 
      
 
-
      This is why the GitHubPages pattern has a navigation sidebar, to the left
+
      This is why the GitHubPages pattern has a navigation sidebar, to the left
 of the main part of each page. The template file contains a special expansion
-written [[Navigation]], and this expands to the HTML for a column of links.
+written [[Navigation]], and this expands to the HTML for a column of links.
 
      
 
 
      The pattern also has a row of breadcrumbs along the top, for navigation within
 the current web.
 
      
 
-
      §7.  By default, Inweb looks for a file called nav.html in two directories: the
+
      §8.  By default, Inweb looks for a file called nav.html 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.
 
      
 
-
      However, this can be overridden at the command line, with -navigation N,
-where N is the filename for a suitable fragment of navigation HTML, and
+
      However, this can be overridden at the command line, with -navigation N,
+where N is the filename for a suitable fragment of navigation HTML, and
 it can also be preset in the Colony file (see above).
 
      
 
-
      §8.  Inweb in fact makes it easy to write such navigation files, providing
+
      §9.  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 docs site:
+Inweb docs site:
 
      
 
 
      @@ -226,14 +240,14 @@ Inweb docs site
 [[Item "intest"]]
 
      
 
      As this shows, there's some HTML for the top left corner area, and then
-a list of items and submenus. [[Link "overview"]] opens a link to the
-colony item called overview; [[URL "inweb"]] writes a minimal-length
-relative URL to reach the named directory, and [[Docs]] to the home page
-of the Github Docs area for the repository. [[Menu "External"]] begins
-a submenu among the items. [[Item "X"]] makes a menu item whose title is
-X and which links to the colony item called X; [[Item "Y" -> Z]] is
-more general, and makes the text Y point to either an external web page,
-recognised by beginning with http, or else a web cross-reference. Thus:
+a list of items and submenus. [[Link "overview"]] opens a link to the
+colony item called overview; [[URL "inweb"]] writes a minimal-length
+relative URL to reach the named directory, and [[Docs]] to the home page
+of the Github Docs area for the repository. [[Menu "External"]] begins
+a submenu among the items. [[Item "X"]] makes a menu item whose title is
+X and which links to the colony item called X; [[Item "Y" -> Z]] is
+more general, and makes the text Y point to either an external web page,
+recognised by beginning with http, or else a web cross-reference. Thus:
 
      
 
 
      @@ -250,12 +264,12 @@ example:
 
           [[Item "<github.png> github" -> https://github.com/ganelson/intest]]
 
      
-
      This icon should be in the docs home of the repository. Note that the
-GithubPages pattern automatically includes the github.png icon, so
+
      This icon should be in the docs home of the repository. Note that the
+GithubPages pattern automatically includes the github.png icon, so
 that one's guaranteed to be present.
 
      
 
-
      §9. The trail of breadcrumbs. Inweb automatically adds web, chapter and section titles to the trail of
+
      §10. The trail of breadcrumbs. Inweb automatically adds web, chapter and section titles to the trail of
 breadcrumbs above each page: for example,
 
      
 
@@ -269,15 +283,15 @@ crumbs to the left. Suppose we want:
 
       Home > Beth > Chapter 4 > File Organisation
 
      
-
      where Home is a link to example/docs/index.html. One way is to run Inweb
-with -breadcrumb 'Home:index.html'; another is to add this to the Colony
+
      where Home is a link to example/docs/index.html. One way is to run Inweb
+with -breadcrumb 'Home:index.html'; another is to add this to the Colony
 file, as
 
      
 
 
           breadcrumbs: "Home: index.html"
 
      
-
      We can add more than one, by, e.g., -breadcrumb 'Home:index.html' -breadcrumb 'Webs: webs.html'.
+
      We can add more than one, by, e.g., -breadcrumb 'Home:index.html' -breadcrumb 'Webs: webs.html'.
 
      
 
 
      @@ -289,7 +303,10 @@ file, as
 
           breadcrumbs: "Overview: //overview//"
 
      
-
      makes a link to the web/module called overview in the colony file.
+
      makes a link to the web/module called overview in the colony file.
+
      
+
+
      §11. Adding custom HTML, CSS and such. This is done by creating a new pattern: see Advanced Weaving with Patterns.
 
      
 
 
      
diff --git a/docs/inweb/M-rc.html b/docs/inweb/M-rc.html
index 6804b11..aacd3f9 100644
--- a/docs/inweb/M-rc.html
+++ b/docs/inweb/M-rc.html
@@ -37,7 +37,7 @@
 
 
      The current help information as it would be printed at the command line.
      
 
-
      §1.  Running Inweb with -help currently produces the following summary:
+
      §1.  Running Inweb with -help currently produces the following summary:
 
      
 
 
      @@ -105,7 +105,7 @@
 -help                    print this help information
 -log X                   write the debugging log to include diagnostics on X
 -version                 print out version number
-
      §2.  Running Inweb with -show-languages currently produces the following list
+
      §2.  Running Inweb with -show-languages currently produces the following list
 of programming languages for which support is provided in the standard
 distribution:
 
      
diff --git a/docs/inweb/M-spl.html b/docs/inweb/M-spl.html
index cfe5250..bc90e66 100644
--- a/docs/inweb/M-spl.html
+++ b/docs/inweb/M-spl.html
@@ -47,11 +47,11 @@ the language mean.
 
      
 
 
      The Contents section of each web specifies its language with a line like
-Language: C. This language name has to be one which Inweb knows, or, more
+Language: C. This language name has to be one which Inweb knows, or, more
 exactly, one for which it can find a "language definition file". These are
-stored in the Languages subdirectory of the inweb distribution, and if a
-language is called L then its file is L.ildf. You can see the languages
-currently available to Inweb by using -show-languages. At present, a newly
+stored in the Languages subdirectory of the inweb distribution, and if a
+language is called L then its file is L.ildf. You can see the languages
+currently available to Inweb by using -show-languages. At present, a newly
 installed Inweb replies like so:
 
      
 
@@ -77,17 +77,17 @@ installed Inweb replies like so:
 Perl: The scripting language Perl 5
 Plain Text: For text files which are not programs
 
      §2.  So what if you want to write a literate program in a language not on that
-list? One option is to give the language as None. (Note that this is
+list? One option is to give the language as None. (Note that this is
 different from simply not declaring a language — if your web doesn't say
-what language it is, Inweb assumes C.) None is fine for tangling, though
+what language it is, Inweb assumes C.) None is fine for tangling, though
 it has the minor annoyance that it tangles to a file with the filename
-extension .txt, not knowing any better. But you can cure that with
--tangle-to F for any filename F of your choice. With weaving, though,
-None makes for drab-looking weaves, because there's very little syntax
+extension .txt, not knowing any better. But you can cure that with
+-tangle-to F for any filename F of your choice. With weaving, though,
+None makes for drab-looking weaves, because there's very little syntax
 colouring.
 
      
 
-
      An even more extreme option is Plain Text, which has no syntax colouring
+
      An even more extreme option is Plain Text, which has no syntax colouring
 at all. (But this could still be useful if what you want is to produce an
 annotated explanation of some complicated configuration file in plain text.)
 
      
@@ -99,17 +99,17 @@ open source project are welcome, and then this effort might also benefit others.
 This section of the manual is about how to do it.
 
      
 
-
      Once you have written a definition, use -read-language L at the command
-line, where L is the file defining it. If you have many custom languages,
--read-languages D reads all of the definitions in a directory D. Or, if
+
      Once you have written a definition, use -read-language L at the command
+line, where L is the file defining it. If you have many custom languages,
+-read-languages D reads all of the definitions in a directory D. Or, if
 the language in question is really quite specific to a single web, you can
-make a Dialects subdirectory of the web and put it in there. (A dialect is,
+make a Dialects subdirectory of the web and put it in there. (A dialect is,
 after all, a local language.)
 
      
 
-
      For testing purposes, running with -test-language F -test-language-on G
-reads in a file G of code, and syntax-colours it according to the rules
-for the language defined in the file F, then prints a plain-text diagram
+
      For testing purposes, running with -test-language F -test-language-on G
+reads in a file G of code, and syntax-colours it according to the rules
+for the language defined in the file F, then prints a plain-text diagram
 of the results. (This can then be tested with Intest test cases, as indeed
 Inweb does itself.)
 
      
@@ -120,16 +120,16 @@ Format".) In this section, we'll call it the ILD.
 
 
      The ILD is a plain text file, which is read in line by line. Leading and
 trailing whitespace on each line is ignored; blank lines are ignored; and
-so are comments, which are lines beginning with a # character.
+so are comments, which are lines beginning with a # character.
 
      
 
 
      The ILD contains three sorts of thing:
 
      
 
-
    • (a) Properties, set by lines in the form Name: "C++".
-
    • (b) Keywords, set by lines in the form keyword int.
-
    • (c) A colouring program, introduced by colouring { and continuing until the
-last block of it is closed with a }.
+
    • (a) Properties, set by lines in the form Name: "C++".
+
    • (b) Keywords, set by lines in the form keyword int.
+
    • (c) A colouring program, introduced by colouring { and continuing until the
+last block of it is closed with a }.
 
    
 
    Everything in an ILD is optional, so a minimal ILD is in principle empty. In
 practice, though, every ILD should open like so:
@@ -143,34 +143,34 @@ practice, though, every ILD should open like so:
 with the semi-compulsory ones.
 
    
 
-
    Name. This is the one used by webs in their Language: "X" lines, and should
-match the ILD's own filename: wherever it is stored, the ILD for langauge X
-should be filenamed X.ildf.
+
    Name. This is the one used by webs in their Language: "X" lines, and should
+match the ILD's own filename: wherever it is stored, the ILD for langauge X
+should be filenamed X.ildf.
 
    
 
-
    Details These are used only by -show-languages.
+
    Details These are used only by -show-languages.
 
    
 
-
    Extension. The default file extension used when a web in this format is
-tangled. Thus, a web for a C program called something will normally tangle
-to a file called something.c.
+
    Extension. The default file extension used when a web in this format is
+tangled. Thus, a web for a C program called something will normally tangle
+to a file called something.c.
 
    
 
 
    §6.  Most programming languages contain comments. In some, like Perl, a comment
-begins with a triggering notation (in Perl's case, #) occurring outside of
+begins with a triggering notation (in Perl's case, #) occurring outside of
 quoted material; and it continues to the end of its line. We'll call that a
 "line comment". There are also languages where comments must be the only
 non-whitespace items on their lines: in that case, we'll call them "whole
 line comments". In others, like Inform 7, a comment begins with one notation
-[ and ends with another ], not necessarily on the same line. We'll call
+[ and ends with another ], not necessarily on the same line. We'll call
 those "multiline comments".
 
    
 
-
    Line Comment is the notation for line comments, and Whole Line Comment is
+
    Line Comment is the notation for line comments, and Whole Line Comment is
 the notation for whole line comments.
 
    
 
-
    Multiline Comment Open and Multiline Comment Close, which should exist
+
    Multiline Comment Open and Multiline Comment Close, which should exist
 as a pair or not at all, is the notation for multiline comments.
 
    
 
@@ -185,14 +185,14 @@ as a pair or not at all, is the notation for multiline comments.
 can give notations for these as follows:
 
    
 
-
    String Literal must be a single character, and marks both start and end.
+
    String Literal must be a single character, and marks both start and end.
 
    
 
-
    String Literal Escape is the escape character within a string literal to
-express an instance of the String Literal character without ending it.
+
    String Literal Escape is the escape character within a string literal to
+express an instance of the String Literal character without ending it.
 
    
 
-
    Character Literal and Character Literal Escape are the same thing for
+
    Character Literal and Character Literal Escape are the same thing for
 character literals.
 
    
 
@@ -204,15 +204,15 @@ character literals.
     String Literal Escape: "\\"
     Character Literal: "'"
     Character Literal Escape: "\\"
-

    §8. Next, numeric literals, like 0xFE45 in C, or $$10011110 in Inform 6. +

    §8. Next, numeric literals, like 0xFE45 in C, or $$10011110 in Inform 6. It's assumed that every language allows non-negative decimal numbers.

    -

    Binary Literal Prefix, Octal Literal Prefix, and Hexadecimal Literal Prefix +

    Binary Literal Prefix, Octal Literal Prefix, and Hexadecimal Literal Prefix are notations for non-decimal numbers, if they exist.

    -

    Negative Literal Prefix allows negative decimals: this is usually - if set. +

    Negative Literal Prefix allows negative decimals: this is usually - if set.

    Here, C has: @@ -222,7 +222,7 @@ are notations for non-decimal numbers, if they exist. Hexadecimal Literal Prefix: "0x" Binary Literal Prefix: "0b" Negative Literal Prefix: "-" -

    §9. Shebang is used only in tangling, and is a probably short text added at +

    §9. Shebang is used only in tangling, and is a probably short text added at the very beginning of a tangled program. This is useful for scripting languages in Unix, where the opening line must be a "shebang" indicating their language. For example, Perl defines: @@ -236,26 +236,26 @@ For example, Perl defines:

    §10. 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 #line to tell it that a contiguous extract follows +preprocessor directive #line to tell it that a contiguous extract follows from the given file. Quite a few languages support notations like this, which most users never use.

    When tangling, Inweb is just such a rearranging tool, and it inserts line -markers automatically for languages which support them: Line Marker specifies +markers automatically for languages which support them: Line Marker specifies that this language does, and gives the notation. For example, C provides: 

         Line Marker: "#line %d \"%f\"\n"
    -

    Here %d expands to the line number, and %f the filename, of origin. +

    Here %d expands to the line number, and %f the filename, of origin.

    §11. When a named paragraph is used in code, and the tangler is "expanding" it to its contents, it can optionally place some material before and after the -matter added. This material is in Before Named Paragraph Expansion and -After Named Paragraph Expansion, which are by default empty. +matter added. This material is in Before Named Paragraph Expansion and +After Named Paragraph Expansion, which are by default empty.

    For C and all similar languages, we recommend this: @@ -281,8 +281,8 @@ matter added. This material is in }

    so that any variables defined inside "Do something dramatic" have limited -scope, and so that multi-line macros are treated as a single statement by if, -while and so on. +scope, and so that multi-line macros are treated as a single statement by if, +while and so on.

    (The new-line before the opening brace is not for aesthetic purposes; we never @@ -290,13 +290,13 @@ care much about the aesthetics of tangled C code, which is not for human eyes. It's in case of any problems arising with line comments.)

    -

    §12. When the author of a web makes definitions with @d or @e, Inweb will +

    §12. When the author of a web makes definitions with @d or @e, Inweb will need to tangle those into valid constant definitions in the language concerned. It can only do so if the language provides a notation for that.

    -

    Start Definition begins; Prolong Definition, if given, shows how to -continue a multiline definition (if they are allowed); and End Definition, +

    Start Definition begins; Prolong Definition, if given, shows how to +continue a multiline definition (if they are allowed); and End Definition, if given, places any ending notation. For example, Inform 6 defines:

    @@ -304,7 +304,7 @@ if given, places any ending notation. For example, Inform 6 defines: Start Definition: "Constant %S =\s" End Definition: ";\n" -

    where %S expands to the name of the term to be defined. Thus, we might tangle +

    where %S expands to the name of the term to be defined. Thus, we might tangle out to:

    @@ -317,8 +317,8 @@ out to:

    §13. Inweb needs a notation for conditional compilation in order to handle some of its advanced features for tangling tagged material: the Inform project makes use of this to handle code dependent on the operating system in use. -If the language supports it, the notation is in Start Ifdef and End Ifdef, -and in Start Ifndef and End Ifndef. For example, Inform 6 has: +If the language supports it, the notation is in Start Ifdef and End Ifdef, +and in Start Ifndef and End Ifndef. For example, Inform 6 has: 

    @@ -327,13 +327,13 @@ and in Start Ifndef    Start Ifndef: "#ifndef %S;\n"
     End Ifndef: "#endif; ! %S\n"
    -

    which is a subtly different notation from the C one. Again, %S expands to +

    which is a subtly different notation from the C one. Again, %S expands to the name of the term we are conditionally compiling on.

    -

    §14. Supports Namespaces must be either true or false, and is by default -false. If set, then the language allows identifier names to include -dividers with the notation ::; section headings can declare that all of +

    §14. Supports Namespaces must be either true or false, and is by default +false. If set, then the language allows identifier names to include +dividers with the notation ::; section headings can declare that all of their code belongs to a single namespace; and any functions detected in that code must have a name using that namespace.

    @@ -342,11 +342,11 @@ code must have a name using that namespace. having them: InC uses it to extend C.

    -

    §15. Suppress Disclaimer is again true or false, and by default false. +

    §15. Suppress Disclaimer is again true or false, and by default false. The disclaimer is a comment placed into a tangle declaring that the file has been auto-generated by Inweb and shouldn't be edited. (The comment only appears in comment notation has been declared for the language: so -e.g., the Plain Text ILD doesn't need to be told to Suppress Disclaimer +e.g., the Plain Text ILD doesn't need to be told to Suppress Disclaimer since it cannot tangle comments anyway.)

    @@ -370,7 +370,7 @@ be detected. fun seekHigherAuthority = ...

    and read them as function declarations. The function name matches the bracketed -part of the regular expression, and in this case is seekHigherAuthority. +part of the regular expression, and in this case is seekHigherAuthority. Similarly for

    @@ -378,20 +378,20 @@ Similarly for Type Declaration Notation: /struct \.([A-Za-z_][A-Za-z0-9_]*) =.*/

    §17. Secret Features. It is not quite true that everything a language can do is defined by the ILD. Additional features are provided to C-like languages to unravel their functions -and typedefs. At present, these are hard-wired into Inweb, and it will take +and typedefs. At present, these are hard-wired into Inweb, and it will take further thought to work out how to express them in LDFs.

    -

    The property C-Like, by default false, enables these features. +

    The property C-Like, by default false, enables these features.

    -

    (In addition, a language whose name is InC gets still more features, but +

    (In addition, a language whose name is InC gets still more features, but those are not so much a failing of ILDF as because Inweb is itself a sort of -compiler for InC — see elsewhere in this manual.) +compiler for InC — see elsewhere in this manual.)

    §18. Keywords. Syntax colouring is greatly helped by knowing that certain identifier names -are special: for example, void is special in C. These are often called +are special: for example, void is special in C. These are often called "reserved words", in that they can't be used as variable or function names in the language in question. For C, then, we include the line:

    @@ -400,14 +400,14 @@ in the language in question. For C, then, we include the line: keyword void

    Keywords can be declared in a number of categories, which are identified by -colour name: the default is !reserved, the colour for reserved words. But +colour name: the default is !reserved, the colour for reserved words. But for example: 

         keyword isdigit of !function
    -

    makes a keyword of colour !function. +

    makes a keyword of colour !function.

    §19. Syntax colouring program. That leads nicely into how syntax colouring is done. @@ -424,17 +424,17 @@ palette of possibilities: !function !identifier !plain !reserved !string

    Each character has its own colour. At the start of the process, every -character is !plain. +character is !plain.

    §20. At the first stage, Inweb uses the language's comment syntax to work out what part of the code is commentary, and what part is "live". Only the live -part goes forward into stage two. All comment material is coloured !comment. +part goes forward into stage two. All comment material is coloured !comment.

    At the second stage, Inweb uses the syntax for literals. Character literals -are painted in !character, string literals in !string, identifiers in -!identifier, and numeric literals as !constant. +are painted in !character, string literals in !string, identifiers in +!identifier, and numeric literals as !constant.

    At the third stage, Inweb runs the colouring program for the language (if @@ -443,11 +443,11 @@ runs only on the live material; it cannot affect the commented-out matter.

    When a colouring program begins running, then, everything is coloured in -one of the following: !character, !string, !identifier, !constant, -and !plain. +one of the following: !character, !string, !identifier, !constant, +and !plain.

    -

    §21. A colouring program begins with colouring { and ends with }. The +

    §21. A colouring program begins with colouring { and ends with }. The empty program is legal but does nothing:

    @@ -466,9 +466,9 @@ block, that's a line of source code. Blocks normally contain one or more marble => !function } -

    Rules take the form of "if X, then Y", and the => divides the X from the Y. +

    Rules take the form of "if X, then Y", and the => divides the X from the Y. This one says that if the snippet consists of the word "marble", then colour -it !function. Of course this is not very useful, since it would only catch +it !function. Of course this is not very useful, since it would only catch lines containing only that one word. So we really want to narrow in on smaller snippets. This, for example, applies its rule to each individual character in turn: @@ -480,7 +480,7 @@ in turn: K => !identifier } } -

    §22. In the above examples, K and marble appeared without quotation marks, +

    §22. In the above examples, K and marble appeared without quotation marks, but they were only allowed to do that because (a) they were single words,

    @@ -492,23 +492,23 @@ marks. For example, in 
         "=>" => !reserved
    -

    the => in quotes is just text, whereas the one outside quotes is being +

    the => in quotes is just text, whereas the one outside quotes is being used to divide a rule.

    -

    If you need a literal double quote inside the double-quotes, use \"; and -use \\ for a literal backslash. For example: +

    If you need a literal double quote inside the double-quotes, use \"; and +use \\ for a literal backslash. For example: 

         "\\\"" => !reserved
    -

    actually matches the text \". +

    actually matches the text \".

    -

    §23. The six splits. characters is an example of a "split", which splits up the original snippet -of text — say, the line let K = 2 — into smaller, non-overlapping snippets -— in this case, nine of them: l, e, t, , K, , =, , and 2. +

    §23. The six splits. characters is an example of a "split", which splits up the original snippet +of text — say, the line let K = 2 — into smaller, non-overlapping snippets +— in this case, nine of them: l, e, t, , K, , =, , and 2. Every split is followed by a block of rules, which is applied to each of the pieces in turn. Inweb works sideways-first: thus, if the block contains rules R1, R2, ..., then R1 is applied to each piece first, then R2 to each piece, @@ -518,14 +518,14 @@ and so on.

    There are several different ways to split, all of them written in the plural, to emphasize that they work on what are usually multiple things. Rules, on the other hand, are written in the singular. Splits are not allowed -to be followed by =>: they always begin a block. +to be followed by =>: they always begin a block.

    -

    1. characters splits the snippet into each of its characters. +

    1. characters splits the snippet into each of its characters.

    -

    2. characters in T splits the snippet into each of its characters which -lie inside the text T. For example, here is a not very useful ILD for +

    2. characters in T splits the snippet into each of its characters which +lie inside the text T. For example, here is a not very useful ILD for plain text in which all vowels are in red:

    @@ -558,7 +558,7 @@ plain text in which all vowels are in red:

    -

    3. The split instances of X narrows in on each usage of the text X inside +

    3. The split instances of X narrows in on each usage of the text X inside the snippet. For example,

    @@ -585,12 +585,12 @@ the snippet. For example, Jacob first appears in the Book of Genesis, the son of Isaac and Rebecca, the grandson of Abraham, Sarah and Bethuel, the nephew of Ishmael. -

    Note that it never runs in an overlapping way: the snippet === would be -considered as having only one instance of == (the first two characters), -while ==== would have two. +

    Note that it never runs in an overlapping way: the snippet === would be +considered as having only one instance of == (the first two characters), +while ==== would have two.

    -

    4. The split runs of C, where C describes a colour, splits the snippet +

    4. The split runs of C, where C describes a colour, splits the snippet into non-overlapping contiguous pieces which have that colour. For example:

    @@ -649,15 +649,15 @@ in "so-called". if (x == 1) printf("Hello!");

    The split divides the line up into three runs, and the inner block runs three -times: on if, then x, then printf. Only the third time has any effect. +times: on if, then x, then printf. Only the third time has any effect.

    -

    As a special form, runs of unquoted means "runs of characters not painted -either with !string or !character". This is special because unquoted is +

    As a special form, runs of unquoted means "runs of characters not painted +either with !string or !character". This is special because unquoted is not a colour.

    -

    5. The split matches of /E/, where /E/ is a regular expression (see below), +

    5. The split matches of /E/, where /E/ is a regular expression (see below), splits the snippet up into non-overlapping pieces which match it: possibly none at all, of course, in which case the block of rules is never used. This is easier to demonstrate than explain: @@ -693,10 +693,10 @@ This is easier to demonstrate than explain:

    -

    6. Lastly, the split brackets in /E/ matches the snippet against the -regular expression E, and then runs the rules on each bracketed +

    6. Lastly, the split brackets in /E/ matches the snippet against the +regular expression E, and then runs the rules on each bracketed subexpression in turn. (If there is no match, or there are no bracketed -terms in E, nothing happens.) +terms in E, nothing happens.) 

    @@ -728,10 +728,10 @@ terms in E, not

    What happens here is that the expression has two bracketed terms, one for the letter, one for the number; the rule is run first on the letter, then -on the number, and both are turned to !function. +on the number, and both are turned to !function.

    -

    §24. The seven ways rules can apply. Rules are the lines with a => in. As noted, they take the form "if X, then +

    §24. The seven ways rules can apply. Rules are the lines with a => in. As noted, they take the form "if X, then Y". The following are the possibilities for X, the condition.

    @@ -757,7 +757,7 @@ exactly that text. For example,

    3. X can require the whole snippet to be of a particular colour, by writing -coloured C. For example: +coloured C. For example: 

    @@ -771,23 +771,23 @@ exactly that text. For example,
 
    
 
 
    4. X can require the snippet to be one of the language's known keywords, as
-declared earlier in the ILD by a keyword command. The syntax here is
-keyword of C, where C is a colour. For example:
+declared earlier in the ILD by a keyword command. The syntax here is
+keyword of C, where C is a colour. For example:
 
    
 
 
         keyword of !element => !element
 
    
-
    says: if the snippet is a keyword declared as being of colour !element,
+
    says: if the snippet is a keyword declared as being of colour !element,
 then actually colour it that way. (This is much faster than making many
 comparison rules in a row, one for each keyword in the language; Inweb has
 put all of the registered keywords into a hash table for rapid lookup.)
 
    
 
 
    5. X can look at a little context before or after the snippet, testing it
-with one of the following: prefix P, spaced prefix P,
-optionally spaced prefix P. These qualifiers have to do with whether white
-space must appear after P and before the snippet. For example,
+with one of the following: prefix P, spaced prefix P,
+optionally spaced prefix P. These qualifiers have to do with whether white
+space must appear after P and before the snippet. For example,
 
    
 
 
    @@ -795,11 +795,11 @@ space must appear after P        prefix optionally spaced -> => !element
     }
 
    
-
    means that any identifier occurring after a -> token will be coloured
-as !element. Similarly for suffix.
+
    means that any identifier occurring after a -> token will be coloured
+as !element. Similarly for suffix.
 
    
 
-
    6. X can test the snippet against a regular expression, with matching /E/.
+
    6. X can test the snippet against a regular expression, with matching /E/.
 For example:
 
    
 
@@ -808,8 +808,8 @@ For example:
         matching /.*x.*/ => !element
     }
    -

    ...turns any identifier containing a lower-case x into !element colour. -Note that matching /x/ would not have worked, because our regular expression +

    ...turns any identifier containing a lower-case x into !element colour. +Note that matching /x/ would not have worked, because our regular expression is required to match the entire snippet, not just somewhere inside.

    @@ -823,7 +823,7 @@ is required to match the entire snippet, not just somewhere inside.

    7. Whenever a split takes place, Inweb keeps count of how many pieces there are, and different rules can apply to differently numbered pieces. The notation -is number N, where N is the number, counting from 1. For example, +is number N, where N is the number, counting from 1. For example, 

    @@ -873,10 +873,10 @@ is number N, wh
 Those lovers scorn whom that love doth possess?
 Do they call virtue there ungratefulness?
    -

    We can also cycle through a set of possibilities with number N of M, -where this time the count runs 1, 2, ..., M, 1, 2, ..., M, 1, ... and -so on. Thus number 1 of 3 would work on the 1st, 4th, 7th, ... times; -number 2 of 3 on the 2nd, 5th, 8th, ...; number 3 of 3 on the 3rd, 6th, +

    We can also cycle through a set of possibilities with number N of M, +where this time the count runs 1, 2, ..., M, 1, 2, ..., M, 1, ... and +so on. Thus number 1 of 3 would work on the 1st, 4th, 7th, ... times; +number 2 of 3 on the 2nd, 5th, 8th, ...; number 3 of 3 on the 3rd, 6th, 9th, and so on. This, for example, paints the output from the painting algorithm in Inweb:

    @@ -920,7 +920,7 @@ to highlight the colours given to the characters in the original. Thus: rrrpipppnnpp!!!!!!!!!!!!!!!!!!!! Imaginary::function(x, beta); fffffffffffffffffffpippiiiipp -

    §25. Any condition can be reversed by preceding it with not. For example, +

    §25. Any condition can be reversed by preceding it with not. For example, 

    @@ -932,7 +932,7 @@ simpler:
 
    1. If Y is the name of a colour, the snippet is painted in that colour.
 
    
 
-
    2. If Y is an open brace {, then it introduces a block of rules which are
+
    2. If Y is an open brace {, then it introduces a block of rules which are
 applied to the snippet only if this rule has matched. For example,
 
    
 
@@ -942,16 +942,16 @@ applied to the snippet only if this rule has matched. For example,
         optionally spaced prefix -> => !element
     }
    -

    means that if the original condition keyword !element applies, then two +

    means that if the original condition keyword !element applies, then two further rules are applied.

    By default, the colour is applied to the snippet. For prefix or suffix rules (see above), it can also be applied to the prefix or suffix: use -the notation => C on both or => C on suffix or => C on prefix. +the notation => C on both or => C on suffix or => C on prefix.

    -

    3. If Y is the word debug, then the current snippet and its colouring +

    3. If Y is the word debug, then the current snippet and its colouring are printed out on the command line. Thus:

    @@ -962,7 +962,7 @@ are printed out on the command line. Thus: } } -

    The rule => debug is unconditional, and will print whenever it's reached. +

    The rule => debug is unconditional, and will print whenever it's reached.

    §27. The worm, Ouroboros. Inweb Language Definition Format is a kind of language in itself, and in diff --git a/docs/inweb/M-tid.html b/docs/inweb/M-tid.html index 8f8f4b5..d48d965 100644 --- a/docs/inweb/M-tid.html +++ b/docs/inweb/M-tid.html @@ -40,9 +40,9 @@

    §1. The InC language. InC is only a little extended from regular C. All of the Inform tools are -written in InC, as is the foundation module of utility routines built in +written in InC, as is the foundation module of utility routines built in to Inweb. It's probably not sensible to use InC in a web which does not -import foundation, and it's certainly not possible to import foundation +import foundation, and it's certainly not possible to import foundation on a web not written in InC. So the two go together.

    @@ -65,7 +65,7 @@ avoided altogether. The Title of This Section.

    That declares that all functions in this section must be have a name which -begins with Namespace::. For example, +begins with Namespace::. For example, 

    @@ -80,8 +80,8 @@ support rather more compartmentalisation than standard C.
 
    
 
 
    The tangler converts these identifiers to regular C identifiers by converting
-the :: to __, so in a debugger, the above function would look like
-Namespace__initialise.
+the :: to __, so in a debugger, the above function would look like
+Namespace__initialise.
 
    
 
 
    Namespaces can be "nested", in the sense that, for example, we could have:
@@ -89,24 +89,24 @@ the :: to 
     [Errors::Fatal::] Handling fatal errors.
-

    §4. The foundation module contains a suite of utility functions for handling +

    §4. The foundation module contains a suite of utility functions for handling strings and streams of text. These are unified in a structure called -text_stream, so that strings in InC webs are almost all values of type -text_stream *. InC provides one convenient feature for this: the notation +text_stream, so that strings in InC webs are almost all values of type +text_stream *. InC provides one convenient feature for this: the notation 

         text_stream *excuse = I"The compiler is not feeling well today.";

    creates a string literal of this type. (This is analogous to ANSI C's little -used syntax for "long strings", which is L"like so".) +used syntax for "long strings", which is L"like so".)

    -

    §5. The words module, a component of the Inform compiler which is not +

    §5. The words module, a component of the Inform compiler which is not included in Inweb, defines natural-language grammars in a notation called Preform. Inweb contains support for writing these directly into code; any paragraph whose code section makes use of this feature is automatically -tagged ^"Preform". This is not the place to document what Preform +tagged ^"Preform". This is not the place to document what Preform notation means, but for example:

    diff --git a/docs/inweb/M-wtaw.html b/docs/inweb/M-wtaw.html index 1e8f0a2..67f769a 100644 --- a/docs/inweb/M-wtaw.html +++ b/docs/inweb/M-wtaw.html @@ -48,8 +48,8 @@ the program.

    Such a file should be a UTF-8 encoded plain text file with the file -extension .inweb. The following is a "hello world" example, which can -be found in the Inweb distribution as inweb/Examples/hellow.inweb: +extension .inweb. The following is a "hello world" example, which can +be found in the Inweb distribution as inweb/Examples/hellow.inweb: 

    @@ -65,7 +65,7 @@ be found in the Inweb distribution as         printf("Hello world!\n");
     }

    §2. This of course is just a regular C "hello world" program written below -the @ = marker, and some metadata written above it. The metadata above +the @ = marker, and some metadata written above it. The metadata above is called the "contents section": for a larger web, it would expand out to something more like a contents page, though here it's more like a title page. The Title, Author and Purpose make no functional difference @@ -75,10 +75,10 @@ setting is another matter, as we shall see.

    The contents end, and the code begins, when the first "paragraph" begins. Code in an Inweb web is divided into paragraphs. The core Inform compiler -currently has 8362 paragraphs, whereas hellow has just one. (If you are +currently has 8362 paragraphs, whereas hellow has just one. (If you are reading this documentation in a web page or a PDF, you will see that it's divided up into little numbered sections: those are individual paragraphs -from the inweb web.) More on this below, but the use of an @ character +from the inweb web.) More on this below, but the use of an @ character in column 1 of the web file is what marks a paragraph break.

    @@ -92,9 +92,9 @@ a comfortably legible version for human eyes instead. Let's now tangle: web "hellow": 1 section(s) : 1 paragraph(s) : 9 line(s) tangling <inweb/Examples/hellow.c> (written in C) -

    And inweb/Examples/hellow.c is now a regular C program which can then be +

    And inweb/Examples/hellow.c is now a regular C program which can then be compiled. If we had wanted it to be written somewhere else, or called -something else, we could have used -tangle-to F to specify a file F +something else, we could have used -tangle-to F to specify a file F to create instead.

    @@ -103,14 +103,14 @@ we take a look at this one to see what has happened, two things are worth noting.

    -
  • (a) First, the use of the #line C preprocessor feature, which ensures that +
  • (a) First, the use of the #line C preprocessor feature, which ensures that any compilation errors occurring will be reported at the correct point of origin in the original Inweb file, not in the tangled file. -
  • (b) Secondly, notice that the main function has automatically been +
  • (b) Secondly, notice that the main function has automatically been predeclared at the top of the file. Because Inweb does this for C programs, the programmer can freely call functions defined lower down in the source code, without having to write tiresome predeclarations or header files. (As it -happens, there was no need in the case of main, but nor was there any harm.) +happens, there was no need in the case of main, but nor was there any harm.) 

    @@ -123,8 +123,8 @@ happens, there was no need in the case of     int main(int argc, char *argv[]) {
         printf("Hello world!\n");
     }
-

    §3. So much for tangling: we can also weave. hellow is so uninteresting -to look at that this seems a good point to switch to inweb/Examples/twinprimes.inweb, +

    §3. So much for tangling: we can also weave. hellow is so uninteresting +to look at that this seems a good point to switch to inweb/Examples/twinprimes.inweb, a C program to find twin prime numbers. If we weave:

    @@ -133,23 +133,23 @@ a C program to find twin prime numbers. If we weave: web "twinprimes": 1 section(s) : 4 paragraph(s) : 48 line(s) [Complete Program: HTML -> inweb/Examples/twinprimes.html] -

    As with tangling, we can override this destination with -weave-to F, telling +

    As with tangling, we can override this destination with -weave-to F, telling Inweb to weave into just a single file (which in this instance it was going -to do anyway) and call it F; or we can similarly -weave-into D, telling -Inweb to weave a set of file into the directory D, rather than the usual -Woven subdirectory of the web in question. +to do anyway) and call it F; or we can similarly -weave-into D, telling +Inweb to weave a set of file into the directory D, rather than the usual +Woven subdirectory of the web in question.

    -

    By default, -weave makes an HTML representation of the program. (On a larger +

    By default, -weave makes an HTML representation of the program. (On a larger web, with multiple sections, it would make a set of linked pages, but here there's just one.) This can then be looked at with a browser such as Chrome or Safari. HTML is not the only format we can produce. Inweb performs the weave -by following a "pattern", and it has several patterns built in, notably HTML, -Ebook and TeX. +by following a "pattern", and it has several patterns built in, notably HTML, +Ebook and TeX.

    -

    Running Inweb with -weave-as P tells it to weave with pattern P; the -plain command -weave is equivalent to -weave-as HTML. The Ebook pattern +

    Running Inweb with -weave-as P tells it to weave with pattern P; the +plain command -weave is equivalent to -weave-as HTML. The Ebook pattern makes an EPUB file suitable for readers such as Apple's Books app, but that would be overkill for such a tiny program. Instead:

    @@ -158,9 +158,9 @@ would be overkill for such a tiny program. Instead: $ inweb/Tangled/inweb inweb/Examples/twinprimes.inweb -weave-as TeX

    This will only work if you have the mathematical typesetting system TeX -installed, and in particular, the pdftex tool. (This comes as part of +installed, and in particular, the pdftex tool. (This comes as part of the standard TeXLive distribution, so simply "installing TeX" on your -platform will probably install pdftex automatically.) Now the response +platform will probably install pdftex automatically.) Now the response is like so:

    @@ -169,13 +169,13 @@ is like so: web "twinprimes": 1 section(s) : 4 paragraph(s) : 48 line(s) [Complete Program: PDF -> inweb/Examples/twinprimes.tex: 1pp 103K] -

    Inweb automatically creates twinprimes.tex and runs it through pdftex -to produce twinprimes.pdf: it reads over the TeX log file to see how -many pages that comes to, and reports back. All being well, the .tex -and .log files are silently removed, leaving just twinprimes.pdf behind. +

    Inweb automatically creates twinprimes.tex and runs it through pdftex +to produce twinprimes.pdf: it reads over the TeX log file to see how +many pages that comes to, and reports back. All being well, the .tex +and .log files are silently removed, leaving just twinprimes.pdf behind.

    -

    §4. Multi-section webs. The twinprimes.inweb example was a program so small that it could +

    §4. Multi-section webs. The twinprimes.inweb example was a program so small that it could comfortably fit into one source file, but for really large programs, that would be madness. The core Inform compiler, for example, runs to about 210,000 lines of code, and distributes those across 418 source files @@ -191,33 +191,33 @@ a single well-defined component of the whole program.

    A multi-section web is stored as a directory, whose name should be (a short version of) the name of the program. For example, Inweb's own -source is in a directory called inweb. A web directory is a tidy, +source is in a directory called inweb. A web directory is a tidy, self-contained area in which the program can be written, compiled and used.

    Inweb expects that a multi-section web will contain at least two source files, each of which is a UTF-8 encoded text file with the file extension -.w. One source file is special, must always be called Contents.w, +.w. One source file is special, must always be called Contents.w, and must be directly stored in the web directory. All other section files are stored in subdirectories of the web directory:

  • (a) If the web is still relatively small, there may only be a few of these, -stored in a single subdirectory called Sections. +stored in a single subdirectory called Sections.
  • (b) Alternatively (not additionally), a larger web can use chapter -subdirectories called Manual, Preliminaries, Chapter 1, Chapter 2, ..., -Appendix A, Appendix B, ...; preliminaries and appendices being optional. +subdirectories called Manual, Preliminaries, Chapter 1, Chapter 2, ..., +Appendix A, Appendix B, ...; preliminaries and appendices being optional. (There can't be a Chapter 0, though there can be Appendix A, B, C, ..., L.)

    • A multi-section web can contain a variety of other subdirectories as needed. -Two in particular, Woven and Tangled, are automatically created by Inweb +Two in particular, Woven and Tangled, are automatically created by Inweb as needed to store the results of tangling and weaving, respectively: they are not intended to hold any material of lasting value, and can be emptied at any time and regenerated later.

    -

    §5. Uniquely, the Contents.w section provides neither typeset output nor +

    §5. Uniquely, the Contents.w section provides neither typeset output nor compiled code: it is instead a roster telling Inweb about the rest of the web, and how the other sections are organised. It has a completely different syntax from all other sections. (It's essentially a fuller version of the @@ -241,16 +241,16 @@ occupies the whole file.) details; there is then a skipped line, and the roster of sections begins.

    -

    Note that the program's Title need not be the same as the directory-name +

    Note that the program's Title need not be the same as the directory-name for the web, which is useful if the program has a long or file-system-unfriendly -name. The Purpose should be brief enough to fit onto one line. Licence can -also have the US spelling, License; Inweb treats these as equivalent. +name. The Purpose should be brief enough to fit onto one line. Licence can +also have the US spelling, License; Inweb treats these as equivalent. Version number and name are, of course, optional.

    -

    The Language is the programming language in which the code is written: much -more on that later on, but for now, the important ones are probably C, InC -and Plain Text. +

    The Language is the programming language in which the code is written: much +more on that later on, but for now, the important ones are probably C, InC +and Plain Text.

    §6. After the header block of details, then, we have the roster of sections. @@ -268,7 +268,7 @@ unchaptered web, we might have for instance: Renderer

    And then Inweb will expect to find, for instance, the section file -Scan Documentation.w in the Sections directory. +Scan Documentation.w in the Sections directory.

    A larger web, however, won't have a "Sections" directory. It may have a @@ -307,13 +307,13 @@ the sense of documentation.)

    In case of any doubt we can use the following command-line switch to see -how Inweb is actually reading the sections of a web W: +how Inweb is actually reading the sections of a web W: 

         $ inweb/Tangled/inweb W -catalogue -verbose

    §7. Tangling. At this point, it may be worth experimenting with a second mathematical -example: inweb/Examples/goldbach, which is to do with a problem in number +example: inweb/Examples/goldbach, which is to do with a problem in number theory called the Goldbach Conjecture. This is a multi-section web, though really only for the sake of an example: it's still a very small web.

    @@ -353,7 +353,7 @@ is nothing fancy - as before, it's just by specifying a "range", much as will be seen later with weaving - but because it's not normally meaningful to tangle only part of a program, the possible ranges are much more restricted. In fact, the only partial tangles -allowed are for chapters or sections marked in the Contents.w as being +allowed are for chapters or sections marked in the Contents.w as being "Independent". For example:

    @@ -361,7 +361,7 @@ allowed are for chapters or sections marked in the Appendix A: The Standard Rules (Independent Inform 7)

    declares that Appendix A is a sort of sidekick program, written in the -language "Inform 7". As a result, it won't be included in a regular -tangle, +language "Inform 7". As a result, it won't be included in a regular -tangle, and to obtain it we have to:

    @@ -374,8 +374,8 @@ a tangle. This can be done by adding: 
         Header: H
    -

    to the contents page of a web. The heacer file H in question should then -be stored in the web's Headers subdirectory. (At one time, the Foundation +

    to the contents page of a web. The heacer file H in question should then +be stored in the web's Headers subdirectory. (At one time, the Foundation module used this to bring in a Windows-only header file.)

    @@ -392,8 +392,8 @@ a single section, this wouldn't happen.) But with a growing web, that can be cumbersome.

    -

    §11. After setting -weave or -weave-as, we can also optionally choose a -range. The default range is all, so up to now we have implicitly +

    §11. After setting -weave or -weave-as, we can also optionally choose a +range. The default range is all, so up to now we have implicitly been running weaves like these:

    @@ -401,7 +401,7 @@ been running weaves like these: $ inweb inweb/Examples/goldbach -weave all $ inweb inweb/Examples/goldbach -weave-as TeX all -

    The opposite extreme from all is sections. This still weaves the entire +

    The opposite extreme from all is sections. This still weaves the entire web, but now cuts it up into individual files, one for each section. For example,

    @@ -417,7 +417,7 @@ example, inweb/Examples/goldbach/Woven/S-tgc.html inweb/Examples/goldbach/Woven/S-tsoe.html -

    Those abbreviated names S-tgc and S-tsoe are cut down from the full +

    Those abbreviated names S-tgc and S-tsoe are cut down from the full names of the sections involved, "The Goldbach Conjecture" and "The Sieve of Eratosthenes". Similarly,

    @@ -436,7 +436,7 @@ of Eratosthenes". Similarly,

    The index file here is a table of contents offering links to the PDFs.

    -

    An intermediate level of granularity is the range chapters, which makes +

    An intermediate level of granularity is the range chapters, which makes sense only for chaptered webs, and puts each chapter into its own file.

    @@ -444,18 +444,18 @@ sense only for chaptered webs, and puts each chapter into its own file.

    • (a) In a chaptered web, chapters are abbreviated to just their numbers: for -example, the range 2 means "just Chapter 2". The Preliminaries alone is P; -the Manual, M. Appendix A, B, C are A, B, C and so on. (This is why +example, the range 2 means "just Chapter 2". The Preliminaries alone is P; +the Manual, M. Appendix A, B, C are A, B, C and so on. (This is why Appendices can only run up to L.) -
    • (b) In an unchaptered web, S means "all the sections". This is almost but not -quite the same as all: the cover sheet (a sort of title page) is omitted. +
    • (b) In an unchaptered web, S means "all the sections". This is almost but not +quite the same as all: the cover sheet (a sort of title page) is omitted.
    • (c) The abbreviation for a section makes a range of just that section. For -example, S/tgc and S/tsoe in the Goldbach web example, or 2/ec for +example, S/tgc and S/tsoe in the Goldbach web example, or 2/ec for the "Enumerated Constants" section of Chapter 2 of Inweb itself. Note that -running Inweb with -catalogue shows all the sections of a web, and their +running Inweb with -catalogue shows all the sections of a web, and their abbreviations. If it's a nuisance that these section ranges are hard to -predict, run with -sequential to have them simply be X/s1, X/s2, ..., -within each chapter, where X is the chapter range. +predict, run with -sequential to have them simply be X/s1, X/s2, ..., +within each chapter, where X is the chapter range.

      §13. Weave tags. An alternative to a range is to specify a tag. Rather than weaving contiguous @@ -469,7 +469,7 @@ A very few tags are automatically applied by Inweb:

      If the program is for a C-like language, Inweb automatically tags any -paragraph containing a typedef struct with the tag Structures. So, +paragraph containing a typedef struct with the tag Structures. So, for example,

      @@ -478,15 +478,15 @@ for example,

      weaves just the structure definitions culled from a much larger web; this can make a convenient reference. Similarly, any paragraph containing an -illustration is automatically tagged Figures, and any paragraph in an -InC web which defines Preform grammar is automatically tagged Preform. +illustration is automatically tagged Figures, and any paragraph in an +InC web which defines Preform grammar is automatically tagged Preform. (In the Inform project, this is used to generate the PDF of the formal syntax of the language.)

      All other tags must be typed by hand. If the line introducing a paragraph -is marked at the end with ^"Fun", then that paragraph will be tagged -as Fun, and so on. Paragraphs can have multiple tags: +is marked at the end with ^"Fun", then that paragraph will be tagged +as Fun, and so on. Paragraphs can have multiple tags: 

      @@ -502,12 +502,12 @@ as Fun    The original version of the program used an in-place insertion sort, but
     ...
      -

      Here the tag is just Algorithms, but when a -weave-to Algorithms is +

      Here the tag is just Algorithms, but when a -weave-to Algorithms is performed, the caption text "Sorting rulebooks" will be used in a subheading in the resulting booklet.

      -

      Beyond that, an entire section can be tagged from the Contents.w page. +

      Beyond that, an entire section can be tagged from the Contents.w page. For example:

      @@ -517,10 +517,10 @@ For example: The Sieve of Eratosthenes ^"Greek"

      tags every paragraph in the section "The Sieve of Eratosthenes" with the -tag Greek. In this instance, a caption is not allowed. +tag Greek. In this instance, a caption is not allowed.

      -

      Note that if we -weave-to a tag which does not exist - or rather, which no +

      Note that if we -weave-to a tag which does not exist - or rather, which no paragraph in the range has - then rather than producing an empty document, Inweb will halt with an "empty weave request" error.

      @@ -532,16 +532,16 @@ but is not a program in its own right.

      For example, all of the Inform tools (including Inweb itself) make use of -a module called foundation, which is written in InC and provides +a module called foundation, which is written in InC and provides facilities for managing memory, manipulating strings, filenames, and so on. -On the other hand, the Inform project also includes a module called inter -which is used only by the core compiler inform7 and by a wrapper utility -also called inter; in fact, inform7 is entirely divided up into modules, +On the other hand, the Inform project also includes a module called inter +which is used only by the core compiler inform7 and by a wrapper utility +also called inter; in fact, inform7 is entirely divided up into modules, some of which are used only by itself.

      §15. It makes little sense to tangle a module on its own. Instead, a web which -wishes to use a module needs to declare this on its Contents.w page. This +wishes to use a module needs to declare this on its Contents.w page. This is done with a list of "imports", after the metadata but before the list of sections. For example,

      @@ -563,29 +563,29 @@ available to the new web. 
           $ inweb/Tangled/inweb inweb/foundation-module -weave sections

      §16. That's everything there is to say about modules, except where Inweb looks -to find them. When it reads a request from a web W to import a module M, -it looks for a web directory called M-module (note the hyphen). For -example, Import: fruit would look for the directory fruit-module. Inweb +to find them. When it reads a request from a web W to import a module M, +it looks for a web directory called M-module (note the hyphen). For +example, Import: fruit would look for the directory fruit-module. Inweb tries the following locations, in sequence, until it finds it:

      -
    • (1) Directly inside W. -
    • (2) In the directory containing W (i.e., one directory higher up). +
    • (1) Directly inside W. +
    • (2) In the directory containing W (i.e., one directory higher up).
    • (3) Directly inside Inweb's own web directory. -
    • (4) In the directory specified by -import-from D at the command line, if any. +
    • (4) In the directory specified by -import-from D at the command line, if any.

      §17. The section catalogue. Inweb can do a handful of other things. One is to list the contents of a web:

      -
    • (a) -catalogue (or -catalog) lists the sections in the web. -
    • (b) -structures lists the sections, and all of the structure definitions +
    • (a) -catalogue (or -catalog) lists the sections in the web. +
    • (b) -structures lists the sections, and all of the structure definitions made in them (for C-like languages). -
    • (c) -functions lists the sections, with all structure definitions and also +
    • (c) -functions lists the sections, with all structure definitions and also all function definitions.
    -

    In addition, for debugging purposes, -scan shows how Inweb is parsing lines -of source code in the web, and -verbose makes it generally print out more +

    In addition, for debugging purposes, -scan shows how Inweb is parsing lines +of source code in the web, and -verbose makes it generally print out more descriptive output.

    @@ -595,7 +595,7 @@ descriptive output. 
         $ inweb/Tangled/inweb W -makefile M
    -

    creates a makefile for the web W and stores it in M. For example, +

    creates a makefile for the web W and stores it in M. For example, 

    @@ -614,8 +614,8 @@ Ordinarily the script used will be the one stored in
 
         inweb/Materials/makescript.txt
 
    
-
    but this can be changed by using -prototype S, which tells Inweb to use
-S as the script. If a -prototype is given, then there's no need to
+
    but this can be changed by using -prototype S, which tells Inweb to use
+S as the script. If a -prototype is given, then there's no need to
 specify any one web for Inweb to use: this allows Inweb to construct more
 elaborate makefiles for multi-web projects. (This is how the main makefile
 for the Inform project is constructed.)
@@ -630,18 +630,18 @@ tool with a web: for example, uploading it to Github.
 
 
    The files produced by weaving or tangling a web are not significant and should
 probably not be subject to source control: they should be "ignored", in git
-terminology. This means writing a special file called .gitignore which
-specifies the files to be ignored. The following does so for a web W:
+terminology. This means writing a special file called .gitignore which
+specifies the files to be ignored. The following does so for a web W:
 
    
 
 
         $ inweb/Tangled/inweb W -gitignore W/.gitignore
 
    
 
    Once again, Inweb does this by working from a script, this time called
-gitignorescript.txt.
+gitignorescript.txt.
 
    
 
-
    §20. README files. Repositories at Github customarily have README.mk files, in Markdown
+
    §20. README files. Repositories at Github customarily have README.mk files, in Markdown
 syntax, explaining what they are. These of course should probably include
 current version numbers, and it's a pain keeping that up to date. For
 really complicated repositories, containing multiple webs, some automation
@@ -651,32 +651,32 @@ is essential, and once again Inweb can oblige.
 
         $ inweb/Tangled/inweb W -write-me W/README.mk
 
    
-
    expands a script called READMEscript.txt into README.mk. Alternatively,
+
    expands a script called READMEscript.txt into README.mk. Alternatively,
 the script can be specified explicitly:
 
    
 
 
         $ inweb/Tangled/inweb W -prototype MySpecialThang.txt -write-me W/README.mk
-
    §21.  Everything in the script is copied over verbatim except where the @ character
+

    §21. Everything in the script is copied over verbatim except where the @ character is used, which was chosen because it isn't significant in Github's form of -Markdown. @name(args) is like a function call (or, in more traditional +Markdown. @name(args) is like a function call (or, in more traditional language, a macro): it expands out to something depending on the arguments. -args is a comma-separated list of fragments of text, which can themselves -contain further uses of @. (If these fragments of text need to contain -commas or brackets, they can be put into single quotes: @thus(4,',') has -two arguments, 4 and ,.) Three functions are built in: +args is a comma-separated list of fragments of text, which can themselves +contain further uses of @. (If these fragments of text need to contain +commas or brackets, they can be put into single quotes: @thus(4,',') has +two arguments, 4 and ,.) Three functions are built in:

    -
    • (a) @version(A) expands to the version number of A, which is normally the -path to a web; it then produces the value of the [[Version Number]] for -that web. But A can also be the filename of an Inform extension, provided -that it ends in .i7x, or a few other Inform-specific things for which +
      • (a) @version(A) expands to the version number of A, which is normally the +path to a web; it then produces the value of the [[Version Number]] for +that web. But A can also be the filename of an Inform extension, provided +that it ends in .i7x, or a few other Inform-specific things for which Inweb is able to deduce a version number. -
      • (b) @purpose(A) is the same, but for the [[Purpose]] of a web. It's +
      • (b) @purpose(A) is the same, but for the [[Purpose]] of a web. It's blank for everything else. -
      • (c) @var(A,D) is more general, and reads the bibliographic datum D from -the web indicated by A. In fact, @version(A) is an abbreviation for -@var(A,Version Number) and @purpose(A) for @var(A,Purpose), so this +
      • (c) @var(A,D) is more general, and reads the bibliographic datum D from +the web indicated by A. In fact, @version(A) is an abbreviation for +@var(A,Version Number) and @purpose(A) for @var(A,Purpose), so this is really the only one needed.

        @@ -688,9 +688,9 @@ is really the only one needed. * @title - @topic. Ebook in Indoc format, stored at path @path. @end -

        The definition lies between @define and @end commands. This one takes +

        The definition lies between @define and @end commands. This one takes three parameters, and inside the definition, their values can be referred -to as @title, @path and @topic. Functions are free to use other +to as @title, @path and @topic. Functions are free to use other functions:

        @@ -700,12 +700,12 @@ functions: @end

        However, each function needs to have been defined before any line on which -it is actually expanded. A definition of one function A can refer to another -function B not yet defined; but any actual use of A must be made after -both A and B have been defined. So, basically, declare before use. +it is actually expanded. A definition of one function A can refer to another +function B not yet defined; but any actual use of A must be made after +both A and B have been defined. So, basically, declare before use.

        -

        §23. Semantic version numbering and build metadata. When Inweb reads in a web, it also looks for a file called build.txt in +

        §23. Semantic version numbering and build metadata. When Inweb reads in a web, it also looks for a file called build.txt in the web's directory; if that isn't there, it looks for the same file in the current working directory; if that's not there either, never mind.

        @@ -718,7 +718,7 @@ current working directory; if that's not there either, never mind. Build Date: 23 March 2020 Build Number: 6Q26 -

        The bibliographic variables Prerelease and so on are then set from this +

        The bibliographic variables Prerelease and so on are then set from this file. (They can equally well be set by the Contents section of the web, and if so then that takes priority.)

        @@ -731,20 +731,20 @@ or semver, for the web. For example, if the Contents included: 
             Version Number: 6.2.12
        -

        then the semver would be 6.2.12-alpha.1+6Q26. This is accessible within -the web as the variable Semantic Version Number. +

        then the semver would be 6.2.12-alpha.1+6Q26. This is accessible within +the web as the variable Semantic Version Number.

        For more on semvers, see: https://semver.org

        §24. A special advancing mechanism exists to update build numbers and dates. -Running Inweb with -advance-build W checks the build date for web W: +Running Inweb with -advance-build W checks the build date for web W: if it differs from today, then it is changed to today, and the build code is advanced by one.

        -

        Running -advance-build-file B does this for a stand-alone build file B, +

        Running -advance-build-file B does this for a stand-alone build file B, without need of a web.

        diff --git a/docs/inweb/P-htpw.html b/docs/inweb/P-htpw.html index d139972..0c2b8cf 100644 --- a/docs/inweb/P-htpw.html +++ b/docs/inweb/P-htpw.html @@ -54,7 +54,7 @@ Inweb, which is a literate program or "web". Before diving in: fact that it uses some extension syntaxes provided by inweb itself. Turn to The InC Dialect for full details, but essentially: it's plain old C without predeclarations or header files, and where functions have names -like Tags::add_by_name rather than just add_by_name. +like Tags::add_by_name rather than just add_by_name.
      • (c) Inweb makes use of a "module" of utility functions called foundation. This is a web in its own right. There's no need to read it, but you may want to take a quick look at A Brief Guide to Foundation (in foundation) or the @@ -67,10 +67,10 @@ works out where Inweb is installed, then calls The user's choices are stored in an inweb_instructions object, and Inweb -is put into one of four modes: TANGLE_MODE, WEAVE_MODE, ANALYSE_MODE, or -TRANSLATE_MODE.1 Inweb never changes mode: once set, it remains +is put into one of four modes: TANGLE_MODE, WEAVE_MODE, ANALYSE_MODE, or +TRANSLATE_MODE.1 Inweb never changes mode: once set, it remains for the rest of the run. Inweb also acts on only one main web in any run, -unless in TRANSLATE_MODE, in which case none. +unless in TRANSLATE_MODE, in which case none.

        Once it has worked through the command line, Configuration also calls @@ -86,8 +86,8 @@ no traveller returns.

        • 1 Tangling and weaving are fundamental to all LP tools. Analysis means, say, reading a web and listing functions in it. Translation is for side-activities like making makefiles or gitignores. -Strictly speaking there is also NO_MODE for runs where the user simply -asked for -help at the command line. +Strictly speaking there is also NO_MODE for runs where the user simply +asked for -help at the command line. ↩

        §3. Program Control then resumes, calling Main::follow_instructions to act on the inweb_instructions object. If the user did specify a web to work on, PC then goes through three stages to understand it. @@ -102,28 +102,28 @@ and also references to a chapter_md, each of which has at least one section_md.2 The "range text" for each chapter and section is set here, which affects leafnames used in woven websites.3 The -optional build.txt file for a web is read by BuildFiles::read, and the +optional build.txt file for a web is read by BuildFiles::read, and the semantic version number determined at BuildFiles::deduce_semver.

        Where a web imports a module, as for instance the eastertide example does, WebMetadata::get creates a module object for each import. In any event, -it also creates a module called "(main)" to represent the main, non-imported, +it also creates a module called "(main)" to represent the main, non-imported, part of the overall program. Each module object also refers to the chapter_md and section_md objects.4

        The result of Reader::load_web is an object called a web, which expands -on the metadata considerably. If W is a web, W->md produces its web_md -metadata, but W also has numerous other fields. +on the metadata considerably. If W is a web, W->md produces its web_md +metadata, but W also has numerous other fields.

        • 2 For single-file webs like twinprimes, with no contents pages, Inweb makes what it calls an "implied" chapter and section heading. - ↩

        • 3 Range texts are used at the command line, and in -catalogue output, for + ↩

        • 3 Range texts are used at the command line, and in -catalogue output, for example; and also to determine leafnames of pages in a website being woven. -A range is really just an abbreviation. For example, M is the range for the -Manual chapter, 2/tp for the section "The Parser" in Chapter 2. +A range is really just an abbreviation. For example, M is the range for the +Manual chapter, 2/tp for the section "The Parser" in Chapter 2. ↩

        • 4 The difference is that the web_md lists every chapter and section, imported or not, whereas the module lists only those falling under its own aegis. @@ -149,8 +149,8 @@ by foundation:

          §5. The third stage is to call Parser::parse_web. This is where we check that the web is syntactically valid line-by-line, reporting errors if any using by calling Main::error_in_web. Each line is assigned a "category": for -example, the category DEFINITIONS_LCAT is given to lines holding definitions -made with @d or @e. See Line Categories for the complete roster.5 +example, the category DEFINITIONS_LCAT is given to lines holding definitions +made with @d or @e. See Line Categories for the complete roster.5

          The parser also recognises headings and footnotes, but most importantly, it @@ -162,9 +162,9 @@ which is not a trivial algorithm: see N

          It is the parser which finds all of the "paragraph macros", the term used -in the source code for named stretches of code in @<...@> notation. A +in the source code for named stretches of code in @<...@> notation. A para_macro object is created for each one, and every section has its own -collection, stored in a linked_list.7 Similarly, the parser finds all of +collection, stored in a linked_list.7 Similarly, the parser finds all of the footnote texts, and works out their proper numbering; each becomes a footnote object.8

          @@ -187,7 +187,7 @@ paragraphs — sometimes called "sections" by those programs, a different us of the word to ours — are numbered simply 1, 2, 3, ..., through the entire program. Doing this would entail some webs in the Inform project running up to nearly 8000. - ↩

        • 7 In real-world use, to use a dictionary instead would involve more + ↩

        • 7 In real-world use, to use a dictionary instead would involve more overhead than gain: there are never very many paragraph macros per section. ↩

        • 8 Though the parser is not able to check that the footnotes are all used; that's done at weaving time instead. @@ -198,7 +198,7 @@ A line at the top like 

               Language: C
          -

          results in the text "C" being stored in the bibliographic datum "Language", +

          results in the text "C" being stored in the bibliographic datum "Language", and if contents lines for chapters or sections specify other languages,9 the loader stores those in the relevant chapter_md or section_md objects. But to the loader, these are all just names. @@ -233,7 +233,7 @@ to a programming_language. unnecessary now that colonies allow for multiple webs to coexist happily. ↩

        §7. Weaving mode. Let's get back to Program Control, which has now set everything up and is about to take action. What it does depends on which of the four modes Inweb -is in; we'll start with WEAVE_MODE. +is in; we'll start with WEAVE_MODE.

        Weaves are highly comfigurable, so they depend on several factors: @@ -253,8 +253,8 @@ a special setting for "do all chapters one at a time" or "do all sections one at a time", a procedure called The Swarm.

        -

        • 10 For example, Inweb automatically applies the "Functions" tag to any -paragraph defining one (see Types and Functions), and using -weave-tag +

          • 10 For example, Inweb automatically applies the "Functions" tag to any +paragraph defining one (see Types and Functions), and using -weave-tag at the command line filters the weave down to just these. Sing to the tune of Suzanne Vega's "Freeze Tag". ↩

          §8. Program Control begins by attempting to load the weave pattern, with @@ -264,10 +264,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 @@ -305,7 +302,7 @@ or weave_format in question: in eff Language Methods and Format Methods for itemised lists, but for example, to weave a line of C into HTML format, the weaver first calls LanguageMethods::syntax_colour, which in turn calls the method -SYNTAX_COLOUR_WEA_MTID to the programming_language object for C; +SYNTAX_COLOUR_WEA_MTID to the programming_language object for C; and then....

          @@ -313,7 +310,7 @@ and then.... it on Spotify. ↩

        §10. Syntax-colouring is worth further mention, since it demonstrates how language support works. In principle, any programming_language object -can do whatever it likes in response to SYNTAX_COLOUR_WEA_MTID. But if Inweb +can do whatever it likes in response to SYNTAX_COLOUR_WEA_MTID. But if Inweb assigns no particular code to this, what instead happens is that the generic handler function in ACME Support takes on the task.14 This runs the colouring program in the language's definition file, by calling an algorithm @@ -330,7 +327,7 @@ in a low-level interpreter by The PainterSee HTML Formats for HTML and ebook weaving, but see also a suite of useful functions in Colonies which coordinate URLs across websites so that one web's weave can safely link to another's. In particular, cross-references -written in //this notation// are "resolved" by Colonies::resolve_reference_in_weave, +written in //this notation// are "resolved" by Colonies::resolve_reference_in_weave, and the function Colonies::reference_URL turns them into relative URLs from any given file. Within the main web being woven, Colonies::paragraph_URL can make a link to any paragraph of your choice.16 @@ -356,16 +353,16 @@ is used in two ways:

      • (a) A simple version tops and tails a weave, providing, for example, the -HTML header for an HTML page, and closing off its <body>. For historical +HTML header for an HTML page, and closing off its <body>. For historical reasons, these are referred to as "cover sheets". See Indexer::cover_sheet_maker.
      • (b) A more elaborate version with a much richer set of features can make arbitrary constructions, and is used for "index pages" (i.e., contents pages) in The Swarm, and also for recursively dropping in navigation matter to the sidebar of a web page. See Indexer::run_engine. This -is where template/navigation syntax such as [[Link ...]] is handled. +is where template/navigation syntax such as [[Link ...]] is handled.

        -

        §13. Tangling mode. Alternatively, we're in TANGLE_MODE, which is more straightforward. +

        §13. Tangling mode. Alternatively, we're in TANGLE_MODE, which is more straightforward. Program Control simply works out what we want to tangle, selecting the appropriate tangle_target object, and calls Tangler::tangle. Most webs have just one "tangle target", meaning that the whole web makes @@ -384,15 +381,15 @@ following instructions from the language definition file.

        Languages declaring themselves "C-like" have access to special tangling facilities, all implemented with non-ACME method calls: see C-Like Languages. -In particular, for coping with how #ifdef affects #include see +In particular, for coping with how #ifdef affects #include see CLike::additional_early_matter; for predeclaration of functions and -structs and typedefs, see CLike::additional_predeclarations. +structs and typedefs, see CLike::additional_predeclarations.

        The language calling itself "InC" gets even more: see InC Support, and -in particular text_literal for text constants like I"banana" +in particular text_literal for text constants like I"banana" and preform_nonterminal for Preform grammar notation like -<sentence-ending>. +<sentence-ending>.

        • 17 The original intention of this feature was that a program might want @@ -403,19 +400,19 @@ to understand without also reading its format files quite carefully. However, it now seems better practice to make such a sidekick file its own web, and use a colony file to make everything tidy on a woven website. So maybe this feature can go. - ↩

        §14. Analysis mode. Alternatively, we're in ANALYSE_MODE. There's not much to this: Program Control + ↩

      §14. Analysis mode. Alternatively, we're in ANALYSE_MODE. There's not much to this: Program Control simply calls Analyser::catalogue_the_sections, or else makes use of the same -functions as TRANSLATE_MODE would — but in the context of having read in a -web. If it makes a .gitignore file, for example, it does so for that specific -web, whereas if the same feature is used in TRANSLATE_MODE, it does so in +functions as TRANSLATE_MODE would — but in the context of having read in a +web. If it makes a .gitignore file, for example, it does so for that specific +web, whereas if the same feature is used in TRANSLATE_MODE, it does so in the abstract and for no particular web.

      -

      §15. Translation mode. Or, finally, we're in TRANSLATE_MODE. We can: +

      §15. Translation mode. Or, finally, we're in TRANSLATE_MODE. We can:

    • (a) make a makefile by calling Makefiles::write; -
    • (b) make a .gitignore file by calling Git::write_gitignore; +
    • (b) make a .gitignore file by calling Git::write_gitignore;
    • (c) advance the build number in a build file, by calling out to the Foundation code at BuildFiles::advance;
    • (d) run a syntax-colouring test to help debug a programming language definition — diff --git a/docs/inweb/index.html b/docs/inweb/index.html index 1ebba04..86fad82 100644 --- a/docs/inweb/index.html +++ b/docs/inweb/index.html @@ -57,7 +57,7 @@

    • Advanced Weaving with Patterns - - Customise the booklets woven from a web.

      + Customise your weave by creating a new pattern.

    • Supporting Programming Languages - diff --git a/foundation-module/Chapter 8/Bibliographic Data for Webs.w b/foundation-module/Chapter 8/Bibliographic Data for Webs.w index 979171e..46bc414 100755 --- a/foundation-module/Chapter 8/Bibliographic Data for Webs.w +++ b/foundation-module/Chapter 8/Bibliographic Data for Webs.w @@ -70,10 +70,8 @@ void Bibliographic::initialise_data(web_md *Wm) { bd = Bibliographic::set_datum(Wm, I"Strict Usage Rules", I"Off"); bd->on_or_off = TRUE; bd = Bibliographic::set_datum(Wm, I"TeX Mathematics Notation", I"$"); bd = Bibliographic::set_datum(Wm, I"TeX Mathematics Displayed Notation", I"$$"); - bd = Bibliographic::set_datum(Wm, I"TeX Mathematics Plugin", I"MathJax3"); bd = Bibliographic::set_datum(Wm, I"Footnote Begins Notation", I"["); bd = Bibliographic::set_datum(Wm, I"Footnote Ends Notation", I"]"); - bd = Bibliographic::set_datum(Wm, I"Footnotes Plugin", I"Bigfoot"); bd = Bibliographic::set_datum(Wm, I"Code In Commentary Notation", I"|"); bd = Bibliographic::set_datum(Wm, I"Code In Code Comments Notation", I"|"); bd = Bibliographic::set_datum(Wm, I"Cross-References Notation", I"//");