@oblomov

apologies, real life kept reminding me that it exists  

This is the Basic List of #LiterateProgramming Features That I Have Been Missing And Occasionally Implementing In Isolation, But Would Like To Implement Together Sometime Soon:

  • a mechanism for systematically attaching persisting numbers to a web's nodes (chapters, sections, leaves, leaf groups / rubrics if used);
  • a mechanism for generating missing numbers automatically when they, or some of them, have not yet been attached, but in a way that would allow them to persist in the future;
  • a mechanism for querying a selection of nodes from a web into a sub-web, and for patching them back into the underlying web after editing;
  • hashtagging a selection of a web's nodes so they could be extracted together, or disabled/enabled together at processing time, somewhat akin to Knuth's INIT...TINI and STAT...TATS mechanism;
  • a mechanism for mapping a web, or a collection of webs, into a number of smallish hyperlinkable wiki-style pages for easy on-the-web reading (and preferably, for also allowing the wiki-edited web/webs gathered back into a single-file web;
  • a mechanism for presenting a program as a series (or DAG) of /layers/, allowing one to start from a simple model, and then build successive complexity on it by adding to, replacing, or turning off nodes (or chunk lists / capers) of previous layers;
  • a syntax for defining 'records' or 'frames' or 'cards' comprising of sets of chunk / pace definitions that belong logically together, and a mechanism for querying these records, and for tangling them according to templates;
  • a mechanism for loading a table of such records, or a stripe of such a table, from an external source such as a CSV, possibly an SQLite table / view, and possibly a JSON/YAML list of records;
  • a mechanism for treating a tangled file as an immediate input for weaving, to simplify maintenance of the kind of documentation that involves long lists of implemented mechanics;
  • a mechanism for using a single-file web as a self-contained script with (some) embedded configuration, so that the same file could be both directly executable, and as a source for tangling (and, particularlly, for weaving into its documentation).

I have implemented everything on this list at least once, and some things several times. Most of these have a relatively straightforward One Obvious Way to implement them; the concept of records and their potential inheritance / prototype linkage mechanism is the oddball that can be done in a number of mutually incompatible ways.

In case these come up, a couple of terms that I like but that not everybody uses are:
-- an 'article' is a bunch of webbly-wobbly stuff in a single file or a single web page / wikipage;

  • an 'aside' is a formal digression in a narrative, potentially presented as a sidebar box or an unfoldable node on the web, or as a figure comprising of some discussion and some code in the printed form;
  • an 'automatic' table or form (or plot), as contrary to a 'manual' one, is one that is generated by the LP engine (possibly runnign an external tool or script) tools during processing, and may be used as an illustration in the weaved output;
  • a 'caper' is a series of a job's paces that go together;
  • a 'caper sign' is the marker for one or more upcoming paces that belong to a single caper (but may not comprise the whole of this caper);
  • an 'entity' is a set of fields or attributes that go together, but may be presented as multiple forms, and/or external table rows, and presents a single unified node in teration;
  • a 'fiat' is a kind of stand-alone directive that can be embedded into an article for fine processing control;
  • a 'form' is a set of fields or attributes (which may be paces) describing an entity presented together;
  • a 'job' is a whole set of input needed for tangling (and potentially, for weaving);
  • a 'leaf' is the non-outlined bottom level of structural narrative nodes of an article; some people call it a 'chunk' and define it as comprising of some text followed by some code; confusingly, some people call these a 'document chunk' and 'code chunk' correspondingly; Knuth called it 'section';
  • a 'manual' table or form is one that appears explicitly and literally in the input, and is maintained by a sophont, as contrary to an 'automatic' one;
  • 'narrative' is everything in an article (or a job) meant for a sophont to be read, that a machine is not likely to particularly care about;
  • a 'pace' is a single tangleable code chunk;
  • a 'recap' is a pace that can be 'untngled' back into the web by running an external script (but I did not list this feature above, for reasons that I suspect might be good ones);
  • a 'rubric' is a mechanism for tying together a bunch of topically associated leaves presented togeher; Knuth called it 'starred section';
  • a 'self-contained' article is one whose job contains only itself, without a dire need for any other articles or external data files; caper in code being generated during tangling;
  • a 'thematic break' is an anonymous, untitled, non-outlined formal break in the narrative, most commonly represented as a horizontal rule or asterism in woven output;
  • a 'title' is a TOC-outlined hierarchical node of an article, or the notation for introducing such a node; in some cases, these are called 'chapters', 'sections', and 'subsections' by outlining depth
  • 'transclusion' is the process of including a referenced caper in the output of tangling (or in some cases, outputof weaving);
  • a 'view' is a selected subset of nodes of a web or a job that can be handy to read or edit together, but that can not necessarily be tangled without having the rest of the web;

Might also possibly come up, but I consider it a bit problematic:

  • an 'enclave' is a somewhat segregated element in a narrative, which happens to be a common ancestor of both an 'aside' and a 'form' in some of my LP tools, but I'm not quite sure that these things actually go together.
@riley on this will need some time to think about it, although some points I'm not sure I understand at all. More detailed answers to follow once I'm fully woken up