Permanent Links

The stable, machine-accessible part of the documentation tree is rooted on the /tB/ prefix. URLs with this prefix — and the internal links that target them, e.g. docs.twinbasic.com/tB/Modules/Math/Round — are guaranteed not to move. The IDE help system and external links rely on this contract.

What the guarantee covers, and what retires a URL

A published /tB/ URL is never re-pointed: it is not renamed, not restructured, and never made to resolve to a different symbol. A page that moves on disk keeps its permalink, which is why the Default / Built-In split changed no URL. A page that takes over another’s subject declares the old URL in redirect_from:.

The one exception is a symbol that no longer exists in twinBASIC. Its page is removed and its URL goes with it. This is a deliberate decision, not a routine edit. The link check does not notice, because no link inside the tree survives the removal. The build stops instead on the symbol index’s list of every URL it has published, until a run with --update-symbol-baseline records the removal. When you retire a URL:

  • Add a redirect wherever anything can carry the URL. If another page covers the subject now, give it a redirect_from: entry for the old URL. Only a URL nothing can stand in for may 404.
  • Remove the entry from this page in the same commit. A URL listed here that no longer resolves misleads the implementers who read this page to decide what is safe to link to.
  • Name the retired URL in the commit message. The consumers of this contract, above all the IDE help system, are outside this repository, and the message is the only record they can be pointed at.

Renaming a heading breaks anchors the same way: redirect_from: emits whole-page stubs and cannot remap a fragment, so an anchor some page links into breaks silently when its heading is reworded. Anchors named in the sections below are part of the contract, and so is every anchor in the symbol index. A build that loses one fails; pin the old id on the reworded heading with {: #old-id } (Renaming a heading).

/tB/symbols.json — the symbol index

The build generates /tB/symbols.json, which lists every name the reference documents with the URL of the page or heading that documents it. The IDE help add-in looks up the name under the cursor in it. The file’s own URL and every URL in it are part of this contract.

{
  "format": 1,
  "api": 983,
  "packages": {"VBA": "VBA", "Assert": "Assert", "cefPackage": "CEF", ...},
  "interfaces": {"VBA._Collection": "VBA.Collection", "tbIDE.IToolWindowsV1": "tbIDE.ToolWindows", ...},
  "symbols": [
    {"name": "Add", "package": "tbIDE", "container": "ToolWindows", "kind": "method", "url": "/tB/Packages/tbIDE/ToolWindows#add"},
    ...
  ]
}
  • format changes when an entry’s fields change meaning, so a reader can tell it holds a file it does not understand.
  • api is the twinBASIC build whose packages the kinds and members were read from.
  • packages maps each package’s name as code writes it — Assert, cefPackage — to the name its pages use.
  • interfaces maps an interface to the class whose members it declares. The compiler names a member by the interface it is declared on (hovering over Collection.Add says VBA._Collection), so a reader holding the compiler’s answer looks the interface up here first.
  • symbols has one entry per name and URL. name is as the package declares it and is matched without regard to case. package and container are null for the language itself. url is a path below the site’s root: a page’s permalink exactly as written, with the heading’s id after # for a member documented under a heading. kind is one of statement, keyword, operator, directive, attribute, package, module, class, control, interface, enum, type, object, function, sub, property, method, event, constant, variable, field, enumvalue, delegate and member — the last for a name the pages document and the packages do not declare.

A name can have several entries: Add is a method of a dozen classes, and Print is a statement, a method of six classes and a member of Debug. The index does not choose between them; its reader does. The $ form of a function has the entry of its base — Left$ goes to Left — as the section on modules below describes.

/tB/Core/<Statement>

/tB/Modules/<ModuleName>/<Symbol>

Within each VBA module, each procedure, property, or statement has its own page, e.g. LenB: /tB/Modules/Strings/Len. The $-suffixed and B/W variants share the base symbol’s page, so LenB, Len$, etc. all use the Len page.

/tB/Packages/<Package>/…

Each package lives under /tB/Packages/<Package>/. The sub-structure depends on the package: modules, classes, enumerations, sub-objects, and interface members each have their own page.

VBRUN is listed by module, and its members are reached from the module page, as under /tB/Modules/. Every other package is listed page by page, so a new class, control, enumeration, sub-object, or member needs its own bullet here, in the commit that adds the page. Nothing catches the omission, because the link check does not look for pages nothing links to. Authoring Pages covers the other indexes a new page must join.

VBRUN – /tB/Packages/VBRUN/<Module>/

VB – /tB/Packages/VB/<Class>/

WebView2 – /tB/Packages/WebView2/…

Assert – /tB/Packages/Assert/<Module>

CustomControls – /tB/Packages/CustomControls/…

CEF – /tB/Packages/CEF/…

WinEventLogLib – /tB/Packages/WinEventLogLib/<Class>

WinNamedPipesLib – /tB/Packages/WinNamedPipesLib/<Class>

WinServicesLib – /tB/Packages/WinServicesLib/…

tbIDE – /tB/Packages/tbIDE/<Class>

WinNativeCommonCtls – /tB/Packages/WinNativeCommonCtls/…

AppGlobalClassObject – /tB/Packages/AppGlobalClassObject/_App/<Member>

The App global object is available in every project without a reference, and each member has its own page. The pages sit under the interface App implements, so every member URL carries an _App/ segment — App.EXEName is at /tB/Packages/AppGlobalClassObject/_App/EXEName. The leading underscore is part of the interface name, after the COM hidden-interface convention; it does not mark a private page.

/tB/Core/Attributes#<attribute>

Note

All non-alphabetic characters, as well as parameters, are removed from the links. All attribute names are in lowercase in the links. E.g. ArrayBoundsChecks(Bool) is referenced as /tB/Core/Attributes#arrayboundschecks.