Skip to content

Commit 1bbccbb

Browse files
authored
Merge pull request #228 from KubaO/contrib-packages
A Contributed Packages section for nine TWINSERV packages, and a `draft` command and workflow for the package indexer
2 parents 05c79a6 + dc3689e commit 1bbccbb

191 files changed

Lines changed: 15968 additions & 57 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎WIP.ExamplesBuild.md‎

Lines changed: 39 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ compiles](docs/Documentation/Authoring.md) in Authoring.md.
1212

1313
## State
1414

15-
Of 1,249 `tb` fences in 613 pages, **1,197 are marked `check_build`** and compile, and 52
16-
are `inert` with a recorded reason. **None is undecided**, so the backlog the census measures
17-
is empty. No fence is an `excerpt`. The run takes about 110 s. 33 of the marked samples are
18-
also `check_run`.
15+
Of 1,530 `tb` fences in 749 pages, **1,370 are marked `check_build`** and compile, and 159
16+
are `inert` with a recorded reason (107 of them OLEGuids' method signatures).
17+
**None is undecided**, so the backlog the census measures is empty. No fence is an
18+
`excerpt`. The run takes about 110 s. 88 of the marked samples are also `check_run`.
1919

2020
New marked samples should come from editing pages, not from marking: the unmarked fences
2121
that are left are not programs (see [What cannot be marked](#what-cannot-be-marked)).
@@ -298,17 +298,50 @@ updates it, which beats a sample that quietly stops demonstrating anything.
298298

299299
Version-controlled exported trees under `test/example-projects/<name>/` --- a `Settings`
300300
file plus `Sources/`, exactly what `node scripts/impexp.mjs export` produces and what `tbrun`
301-
already consumes. Three exist:
301+
already consumes. Three whole ones exist:
302302

303303
| template | references | for |
304304
|---|---|---|
305305
| `console` | stdole, VB (Forms), AppGlobalClassObject | everything by default |
306306
| `packages` | the above plus all eleven other shipped packages | `Reference/Built-In/` and the package tutorials |
307307
| `form` | `console`, a delta | a `check_run` sample that needs a real form: drawing, `Cls`, `Print`, `Scale`, a form property. Never inferred: a fence says `project=form` |
308+
| `contributed-<Package>` | `console`, a delta: one `Settings` referencing one documented TWINSERV package, embedded | `Reference/Contributed/<Package>/` |
308309

309310
(The table is the three whole templates. The deltas over them --- `vb-private`, `cc-private`,
310311
`wnc-private`, `cef-private`, `implicit`, `cef`, `webview2` --- are `TEMPLATE_BASE` in
311-
`scripts/lib/example-batches.mjs`, with `form`.)
312+
`scripts/lib/example-batches.mjs`, with `form` and the `contributed-<Package>` ones, which
313+
`TEMPLATE_BASE` gets from the directories so named.)
314+
315+
**`contributed-<Package>`: packages embedded, not committed.** A project uses a TWINSERV
316+
package by embedding its whole exported tree under `Packages/<symbolId>/`, with a reference
317+
whose `path32` and `path64` are `/Packages/<symbolId>` (an AutoCompleteLib `.twinpack` embeds
318+
AutoCompleteGuids this way). A template commits only that `Settings`; `embeddedPackages`
319+
reads the references, and `fetchEmbedded` in `check_examples.mjs` downloads each package at
320+
the reference's version from TWINSERV into `%TEMP%\tb-twinserv\<id>_<version>.twinpack`,
321+
unpacks it beside, and copies it into every batch staged from the template. The code is not
322+
the repository's to commit: four of the nine ship no licence file, and WinReg embeds WinDevLib,
323+
14 MB.
324+
325+
- **One template per package, because a reader's project references one.** With the nine in
326+
one project, VBA_JSON's `Dictionary` class hid the `Scripting.Dictionary` that WinReg's
327+
samples name.
328+
- **A project does not see the names a package's own references declare.** WinReg embeds
329+
WinDevLib, and its samples' `HKEY_CURRENT_USER`, `REGTYPES` and `BOOL` were unresolved
330+
until `contributed-WinReg` referenced WinDevLib (at the version WinReg embeds, 8.8.0.507)
331+
and the Scripting Runtime itself. The WinReg landing page tells the reader the same.
332+
- **An error inside an embedded package is the package's, and fails nothing**
333+
(`splitPackageFaults`). BigNumberLib 0.0.0.0 and WinReg 0.0.0.0 do not compile on BETA
334+
1005: each passes a pointer to a `ByRef` structure parameter without `ByVal` (TB5001). The
335+
template-alone build finds those rows; the run prints them as a note naming the package
336+
rather than as a template FAIL, every other template row still fails, and the samples are
337+
judged by their own rows as before. Their landing pages say so in a NOTE, and both sections
338+
are excluded from the site until the packages compile; `examples.bat` still compiles their
339+
samples, since it reads every page under `docs/` whatever `exclude:` says.
340+
- **When a section's `indexed_from` moves to a new version, change the version fields in its
341+
`test/example-projects/contributed-<Package>/Settings` with it**, or its samples compile
342+
against the old package. A new contributed section needs a template of its own: a copy of
343+
another's `Settings` with the reference's `id`, `name`, `symbolId`, `path32`, `path64` and
344+
version fields (strings) changed, from the package's own `Settings` and its TWINSERV version.
312345

313346
**Template inheritance.** `TEMPLATE_BASE` names each template's base. The stager copies
314347
base-first, delta-over, so a template holds only the files that *differ*: `vb-private` is

‎WIP.Indexer.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,57 @@ the old tool's at BETA 997, and it takes half a second with no cache.
194194
its 17 values at BETA 997, the first named `" "`, which the committed file lacked until it
195195
was derived again.
196196

197+
## `draft` and the doc-draft workflow
198+
199+
`twin-index draft` turns `report.json` into page plans (`lib/draft-plan.mjs`), and
200+
`indexer/draft/workflow.mjs` is the Claude Code workflow that writes the pages from them.
201+
202+
- **Placement is read from each section, not from a convention**, because the sections do not
203+
share one: the built-in packages keep enumerations in `Enumerations/`, the contributed ones
204+
beside the classes; a class is `X/index.md` with member pages, `X.md` with its members
205+
inline, or `_App/_App.md`. The draft workflow this replaced derived every path from one rule
206+
(`<module>/<symbol>.md`, `<symbol>.md`), which matched no section exactly. Every rule in
207+
`draft-plan.mjs` is a majority over the section's own pages.
208+
- **How well it places, checked by leaving each symbol out** of every section with a store
209+
package (the thirteen built-in and default ones at BETA 997, and the nine contributed ones of
210+
the `contributed-packages` branch) and planning it again: 994 of 998 members land on the file
211+
the section has them on, with its parent and permalink; 138 of 156 types; and the landing
212+
page of each contributed section, planned from the other eight, matches in all nine. The 18
213+
types that miss are layout choices no API shows: six that are the only type of their kind
214+
in their package, with nothing to follow (`AutoComplete.md`, not `AutoComplete/index.md`;
215+
`_App/_App.md`); seven controls laid out unlike their package's other controls; two
216+
`...State` classes kept in their control's folder; CustomControls' `Constants` module, at
217+
the root while its other modules are in `Framework/`; and two collections whose owner's
218+
folder the check had itself taken away. The four members that miss are documented unlike
219+
the others of their kind in their type, or not at all. The rule that places a type in the
220+
folder of the type returning it is limited to folders that already keep a type, because
221+
without that limit it moved Printer under Printers, Dictionary under JsonConverter and
222+
eight others that the sections keep at their roots.
223+
- **A permalink is computed only where the rule holds for every existing page** of the
224+
section (`followsFolders`). On staging at BETA 997 that is every section but VBA's, whose
225+
pages live under `/tB/Modules/`. A section that breaks the rule once gets no computed
226+
permalinks at all, rather than a guess that a sibling page would contradict.
227+
- **The prep is Node and the workflow is thin**, as Wisdom's extract is
228+
([WIP.Wisdom.md](WIP.Wisdom.md)): a workflow script cannot read a file, so everything that
229+
needs the tree --- the pages, their titles and permalinks, the kinds of the types they
230+
document --- is decided by tested code, and the agents get finished decisions. The
231+
manifest passed as `args` names the batch files and nothing more, because `args` is written
232+
out by the calling session, at output-token cost; each agent reads its own batch.
233+
- **No two agents write one file.** A batch is a type with its new members, or one type's
234+
members, and the pages that go on one type's one page are never split across batches. The
235+
lists that several batches would all touch --- the landing page's, and a type page's list of
236+
its members --- are left to one agent per package after its batches finish.
237+
- **The check step compiles before a person reads.** One agent per package runs
238+
`check_examples --only` on the section, at a port of its own (9700 up, clear of the
239+
harness's default 9480), and fixes the pages. A contributed package without a
240+
`contributed-<Package>` template cannot be compiled, and the agent says so.
241+
- **The agents are Sonnet**, as the content agents of the contributed packages were; the
242+
drafts are read against the sources before they are committed, which no model choice
243+
replaces.
244+
- **It is not in the published docs.** `draft` is (Tools-Build), because its plans serve a
245+
person writing pages by hand; the workflow is described here and in `WIP.md`, because
246+
nothing under `docs/Documentation/` may require Claude.
247+
197248
## Open items
198249

199250
- **`diffApi` reports `attributes` as changed as well as `signature` when only a property's

0 commit comments

Comments
 (0)