Ken Johnson
97cbc3e0e8
Two related doc passes: 1. UpdateMessage docs. docs/API.md "Updating & deleting" section previously said "Optional operations. Not every backend implements them -- default returns False." Since v0.6.0 that's wrong: UpdateMessage has header-metadata-only semantics on every backend. Rewrote the section to describe the semantics, typical use cases (flipping attr bits, reply-chain pointers), and the boundary (body / CtrlInfo / SubFields / inline kludges untouched; need Delete + WriteMessage for body changes). Added a note by the .Native escape-hatch example that most previously- native-only operations now have uni-API equivalents. 2. ma.* -> mb.* namespace sweep. The 0.5.0 rename renamed every source unit but the docs kept the old names in code-block `uses` clauses and architecture diagrams. Copy-paste consumers hitting those would get compile errors. Replaced word-boundary ma.<api|types|events|lock|paths|kludge|fmt> references in README.md, docs/API.md, docs/architecture.md, docs/ftsc- compliance.md, and docs/format-notes/dependencies.md with the mb.* form. Left docs/PROPOSAL.md alone -- that is the pre- rename design doc and reads as historical record. All 75 tests pass; full six-target build clean. Retagging v0.6.0 in place since no downstream has pinned yet.
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# External dependencies
|
|
|
|
## Sample test data
|
|
|
|
Real message bases for testing live under `tests/data/` (vendored
|
|
into the repo) for the formats covered by the test suite. Additional
|
|
working bases used during development:
|
|
|
|
- `~/fidonet/msg/` — Hudson, JAM, Squish, FTS-1 *.msg, etc.
|
|
- `~/allfix_dev/f_drive/tpfiles/allfix/wc_dev/testdata/` — WildCat 4
|
|
(7 conferences, MSG/MSG0..MSG6.DAT/IX, DATA/ALLUSERS.DAT, etc.)
|
|
|
|
Tests should open these read-only and verify message counts, first /
|
|
last messages, and specific known attributes. Do NOT write to these
|
|
paths from tests — copy them into a scratch dir first. The Wildcat
|
|
SDK mutates the message database during Open (btis locks, modcounters)
|
|
so even "read" paths must go through a scratch copy.
|
|
|
|
## Authoritative specs
|
|
|
|
The FTSC document collection at `/home/ken/Source Code/ftsc/docs/` is
|
|
the source of truth when validating attribute bits, packet header
|
|
layouts, date strings, and kludge syntax. Key documents we cross-check
|
|
against:
|
|
|
|
- `fts-0001.016` — FTS-1 packet & message format (PKT, *.MSG,
|
|
attributes, date string, kludges)
|
|
- `fsc-0039.001` / `fsc-0039.004` — Type-2+ packet header
|
|
- `fsc-0045.001` — Type-2.2 packet header
|
|
- `fsc-0048.002` — AuxNet Type-2 variant
|
|
- `fsc-0009`, `fsc-0035`, etc. — kludges and control lines
|
|
|
|
Non-FTSC formats follow their original authors' published specs:
|
|
jam.txt (JAM), squish.doc (Squish/Lanius), pcboard.doc, the EzyCom
|
|
reference, and the WildCat 4 SDK headers vendored under `src/wc_sdk/`.
|
|
|
|
When in doubt about an encoding or bit position, reference the spec
|
|
before changing the conversion tables in `mb.types.pas`.
|
|
|
|
## mb.fmt.wildcat.pas
|
|
|
|
The Wildcat backend uses the WildCat 4 SDK vendored at `src/wc_sdk/`.
|
|
The SDK is kept on its own search-path entry (`-Fusrc/wc_sdk`) so
|
|
callers that don't need Wildcat can omit the backend without forcing
|
|
the SDK onto the build line. See the active cleanup pass to trim the
|
|
SDK to only what `mb.fmt.wildcat` actually uses.
|