diff --git a/metanorma.yml b/metanorma.yml index c693a86..56693e6 100644 --- a/metanorma.yml +++ b/metanorma.yml @@ -5,6 +5,7 @@ metanorma: - sources/express-pretty/document.adoc - sources/annotated-express/document.adoc - sources/expressdocs-migration/document.adoc + - sources/expressdocs-framework/document.adoc - sources/express-schema-manifest/document.adoc - sources/express-changes/document.adoc - sources/express-mapping/document.adoc diff --git a/sources/expressdocs-framework/document.adoc b/sources/expressdocs-framework/document.adoc new file mode 100644 index 0000000..4c78b8b --- /dev/null +++ b/sources/expressdocs-framework/document.adoc @@ -0,0 +1,57 @@ += EXPRESSdocs Publishing Framework +:docnumber: 5002 +:edition: 0 +:copyright-year: 2026 +:revdate: 2026-11-14 +:language: en +:title-main-en: EXPRESSdocs Publishing Framework +:doctype: standard +:technical-committee: EXPRESS +:imagesdir: images +:mn-document-class: elf +:mn-output-extensions: xml,html,doc,pdf,rxl +:fullname: Ronald Tse +:surname: Tse +:givenname: Ronald +:affiliation: EXPRESS Language Foundation +:fullname_2: Thomas Thurman +:surname_2: Thurman +:givenname_2: Thomas +:affiliation_2: EXPRESS Language Foundation +:docidentifier: ELF 5002 (draft) +:data-uri-image: +:local-cache-only: +:draft: 0.1 + +// DRAFT: number 5002 is provisional; the final document number is assigned by ELF. +// Enumerated from current practice: metanorma/annotated-express (reference +// templates), metanorma/suma (conforming engine), metanorma/mn-samples-expressdocs +// (conformance corpus), metanorma/iso-10303 (production adoption). + +include::sections/00-foreword.adoc[] + +include::sections/01-scope.adoc[] + +include::sections/02-normrefs.adoc[] + +include::sections/03-terms.adoc[] + +include::sections/04-framework-overview.adoc[] + +include::sections/05-project-layout.adoc[] + +include::sections/06-collection-manifest.adoc[] + +include::sections/07-template-contract.adoc[] + +include::sections/08-anchor-reference.adoc[] + +include::sections/09-urn-identity.adoc[] + +include::sections/10-build-interface.adoc[] + +include::sections/11-delivery-verification.adoc[] + +include::sections/12-performance-contract.adoc[] + +include::sections/13-conformance.adoc[] diff --git a/sources/expressdocs-framework/sections/00-foreword.adoc b/sources/expressdocs-framework/sections/00-foreword.adoc new file mode 100644 index 0000000..b1a7d0c --- /dev/null +++ b/sources/expressdocs-framework/sections/00-foreword.adoc @@ -0,0 +1,17 @@ +[[foreword]] +== Foreword + +This document is a *working draft*. It enumerates the EXPRESSdocs publishing +framework as a contract from current practice, so that implementations other +than the originating one can conform. The normative statements in this draft +are derived from the behaviour of existing implementations, principally the +ISO 10303 (STEP) publishing pipeline; where practice diverges, this draft +states the intended contract and implementations converge towards it. + +ISO/TC 184/SC 4 and other producers of Annotated EXPRESS content are users of +this framework, not its standardizers: authoring follows ELF 5001, publishing +follows this specification. + +Attention is drawn to the possibility that some elements of this document may +be the subject of patent rights. ELF shall not be held responsible for +identifying any or all such patent rights. diff --git a/sources/expressdocs-framework/sections/01-scope.adoc b/sources/expressdocs-framework/sections/01-scope.adoc new file mode 100644 index 0000000..31d30f0 --- /dev/null +++ b/sources/expressdocs-framework/sections/01-scope.adoc @@ -0,0 +1,19 @@ +[[scope]] +== Scope + +This document specifies the EXPRESSdocs publishing framework: an +implementation-neutral contract for rendering Annotated EXPRESS content into +published documentation. It defines: + +* the directory layout of an EXPRESSdocs project; +* the collection manifest that declares documents and schemas to be published; +* the template contract that an implementation shall honour to render each + EXPRESS construct; +* anchor, cross-reference, and URN identity semantics; +* the build interface and its exit behaviour; +* delivery verification, provenance, and signing; +* the performance contract that implementations shall satisfy; +* conformance classes and the conformance corpus. + +The *content* of Annotated EXPRESS documentation — remark types, content +syntax, and usage — is specified in ELF 5001 and is out of scope here. diff --git a/sources/expressdocs-framework/sections/02-normrefs.adoc b/sources/expressdocs-framework/sections/02-normrefs.adoc new file mode 100644 index 0000000..bc18e36 --- /dev/null +++ b/sources/expressdocs-framework/sections/02-normrefs.adoc @@ -0,0 +1,14 @@ +[[normrefs]] +== Normative references + +The following documents are referred to in the text in such a way that some +or all of their content constitutes requirements of this document. + +* *ELF 5001:2024*, _Annotated EXPRESS_ — the content specification for + annotated EXPRESS documentation (remark types, content syntax, usage). +* *ISO 10303-11*, _Industrial automation systems and integration — Product + data representation and exchange — Part 11: Description methods: The + EXPRESS language reference manual_ — the language whose schemas are the + subject of published documentation. +* *RFC 8141*, _Uniform Resource Names (URNs)_ — the syntax of the content + identifiers defined by this framework. diff --git a/sources/expressdocs-framework/sections/03-terms.adoc b/sources/expressdocs-framework/sections/03-terms.adoc new file mode 100644 index 0000000..4ecd1eb --- /dev/null +++ b/sources/expressdocs-framework/sections/03-terms.adoc @@ -0,0 +1,34 @@ +[[terms]] +== Terms and definitions + +==== EXPRESSdocs project + +A directory of source material — EXPRESS schemas, Annotated EXPRESS documents +per ELF 5001, collection manifests, and authoring templates — sufficient for a +conforming implementation to produce published documentation. + +==== collection manifest + +A data document declaring the documents, schemas, and build directives of an +EXPRESSdocs project. It contains no executable logic. + +==== implementation + +A processor that consumes an EXPRESSdocs project and produces published +documentation and delivery artifacts as specified by this document. + +==== derived data + +Content generated by a build from source material, such as extracted concept +datasets or exported schema listings. Derived data is reproducible: it is +never an input to its own production. + +==== template + +An authorable rendering unit (e.g. a Liquid template) bound to one EXPRESS +construct class, through which an implementation renders that construct. + +==== staged build + +An implementation strategy that renders disjoint member subsets in separate +executions against a shared store, then composes the site from the store. diff --git a/sources/expressdocs-framework/sections/04-framework-overview.adoc b/sources/expressdocs-framework/sections/04-framework-overview.adoc new file mode 100644 index 0000000..9f8066e --- /dev/null +++ b/sources/expressdocs-framework/sections/04-framework-overview.adoc @@ -0,0 +1,21 @@ +[[framework-overview]] +== Framework overview + +An EXPRESSdocs project is authored once and published by any conforming +implementation: + +[source] +---- +schemas/ EXPRESS sources (read-only inputs) +documents/ Annotated EXPRESS documents (ELF 5001 content) +site manifest collection manifest (Clause 6) +templates/ authoring templates (Clause 7) +---- +The build (Clause 10) renders the manifest through the template contract +(Clauses 7–9) into a site (Clause 11), under the performance contract +(Clause 12). Authoring is standardized at ELF 5001; this framework +standardizes everything the build does around it. + +The contract is deliberately drawn so that the ISO 10303 corpus — +hundreds of schemas, thousands of documents, production CI — is a +conforming project rather than a special case. diff --git a/sources/expressdocs-framework/sections/05-project-layout.adoc b/sources/expressdocs-framework/sections/05-project-layout.adoc new file mode 100644 index 0000000..45ca682 --- /dev/null +++ b/sources/expressdocs-framework/sections/05-project-layout.adoc @@ -0,0 +1,29 @@ +[[project-layout]] +== Project layout + +An EXPRESSdocs project shall organize source material as follows: + +[source] +---- +schemas/ EXPRESS schema sources (.exp); read-only inputs +documents// Annotated EXPRESS document sources (document.adoc, + per ELF 5001), one directory per document + collection manifest, Clause 6 (conventional name: + metanorma.yml) +templates/ project-level authoring templates, Clause 7 +/ derived data (extracted concepts, exported schema + listings); reproducible, see below +---- + +Requirements: + +* Schema sources shall be treated as read-only inputs. Any annotation + material an implementation synthesizes into a schema listing (e.g. figure + hotspot maps) shall be produced as *derived output at export time* from + external data, never by mutating schema sources. +* Derived data shall be reproducible from source material and build inputs. + A project may commit derived data for review, but a conforming + implementation shall regenerate it from sources and shall not consume it + as an input to its own production. +* Implementations shall write all generated output to paths derived from the + consumer's project root, never into their own installation. diff --git a/sources/expressdocs-framework/sections/06-collection-manifest.adoc b/sources/expressdocs-framework/sections/06-collection-manifest.adoc new file mode 100644 index 0000000..86a4416 --- /dev/null +++ b/sources/expressdocs-framework/sections/06-collection-manifest.adoc @@ -0,0 +1,28 @@ +[[collection-manifest]] +== Collection manifest + +The collection manifest is a data document (YAML) that declares what an +implementation builds. It shall contain no executable logic. + +==== Structure + +* *files* — the documents to render, as source paths (document.adoc entries) + or nested manifests. A document entry declares its output formats and may + declare that its rendered site is split per section (section splitting): + the split is an implementation behavior, the declaration is manifest data. +* *directives* — build directives as single-key entries. Directives are + declarative requests (e.g. `base-dir: collection` — resolve document + includes against the collection root); an implementation that does not + understand a directive shall fail loudly rather than ignore it silently. +* *collection metadata* — organization and collection name for the produced + site. + +==== Requirements + +* Manifest entries identify documents and schemas by path relative to the + project root; an implementation shall resolve them identically regardless + of the working directory the build is invoked from. +* Every manifest node used as a build input shall carry a stable identity so + that generated identifiers derived from it are deterministic (Clause 12). +* The manifest is the single source of document ordering; render completion + order shall never influence manifest-derived ordering. diff --git a/sources/expressdocs-framework/sections/07-template-contract.adoc b/sources/expressdocs-framework/sections/07-template-contract.adoc new file mode 100644 index 0000000..eacac0b --- /dev/null +++ b/sources/expressdocs-framework/sections/07-template-contract.adoc @@ -0,0 +1,33 @@ +[[template-contract]] +== Template contract + +An implementation renders each EXPRESS construct class through *authorable +templates*; the templates are part of the project, not of the implementation. + +==== Template surface + +The template surface shall cover at minimum: schema (identity, statements), +entity (attributes, supertypes, subtypes, where-rules), function and +procedure, rule, constant and type declarations, subtype constraint, USE +FROM and REFERENCE interfaces, ELF 5001 remarks (each remark type per its +content specification), and diagrams with hotspot maps (Clause 8). + +==== Resolution order + +Templates resolve from the most specific to the most general: project +templates, then flavor defaults bundled with the implementation. A project +template overrides a default of the same name; the resolution order itself +shall be deterministic. + +==== Model surface + +Templates receive the parsed EXPRESS model — schemas, entities, attributes, +constraints, interfaces, remarks — through a documented accessor surface. +An implementation shall document every accessor its templates rely upon; +undocumented accessors are not part of the contract and projects relying on +them do so at their own risk. + +==== Compilation + +An implementation shall compile authoring templates once per process and +reuse the compiled forms across documents (Clause 12, P1). diff --git a/sources/expressdocs-framework/sections/08-anchor-reference.adoc b/sources/expressdocs-framework/sections/08-anchor-reference.adoc new file mode 100644 index 0000000..678761a --- /dev/null +++ b/sources/expressdocs-framework/sections/08-anchor-reference.adoc @@ -0,0 +1,34 @@ +[[anchor-reference]] +== Anchor and reference semantics + +==== Anchors + +Anchors identify linkable elements with schema-qualified identifiers, so that +cross-document references resolve globally within a project: + +* schema-level elements: `[[.]]`; +* attribute-level elements: `[[..]]`; +* diagram anchors: `[[.expg]]`, one per EXPRESS-G diagram in + document order. + +An implementation shall emit exactly one anchor per linkable element and +shall support both the schema-qualified form and the bare form +(`[[]]`), resolving the bare form within the scope of the declaring +schema. + +==== Hotspot maps + +Figure hotspot maps bind image regions to targets. A hotspot map is +associated with one image; each target binds a region of the image to a +cross-reference (the ELF 5001 remark syntax supplies the targets). Hotspot +binding shall be exact: a target that names a specific element binds that +element, and the binding shall survive section splitting of the rendered +site (the referenced element may render on another page; the link shall +follow it). + +==== Resolution failures + +A cross-reference whose target does not resolve anywhere in the project is a +verifiable diagnostic (Clause 11), not a silent drop: implementations shall +surface unresolved targets in a structured diagnostic channel, and delivery +verification counts them. diff --git a/sources/expressdocs-framework/sections/09-urn-identity.adoc b/sources/expressdocs-framework/sections/09-urn-identity.adoc new file mode 100644 index 0000000..1d2a442 --- /dev/null +++ b/sources/expressdocs-framework/sections/09-urn-identity.adoc @@ -0,0 +1,15 @@ +[[urn-identity]] +== URN identity + +Published EXPRESS content carries content URNs of the form +`:tech:.`, where `` is the publisher's +URN namespace for the corpus (e.g. `urn:iso:std:iso:10303:-2:ed-2:tech`). +Terminology concepts carry term URNs under the same base. + +* The wildcard form `:tech:*` addresses the whole technical + corpus. +* URNs are stable across builds: the same schema and element yield the same + URN in every build. +* Implementations should make URNs dereferenceable: a static hosting of the + produced site shall serve each URN at a path derived from the URN itself, + negotiating between canonical data and human-readable representations. diff --git a/sources/expressdocs-framework/sections/10-build-interface.adoc b/sources/expressdocs-framework/sections/10-build-interface.adoc new file mode 100644 index 0000000..854170c --- /dev/null +++ b/sources/expressdocs-framework/sections/10-build-interface.adoc @@ -0,0 +1,26 @@ +[[build-interface]] +== Build interface + +A conforming implementation provides a build operation that consumes a +collection manifest (Clause 6) and produces the site (Clause 11). + +==== Required behaviour + +* The build shall resolve all document, schema, and template paths relative + to the project root, independent of the invocation working directory. +* A failing document render shall produce a non-zero build exit code and a + structured diagnostic naming the failed document; a build shall not exit + zero while an expected output is missing or a member failed. +* Incremental builds are permitted: an implementation may skip re-rendering + inputs that are unchanged, keyed by input content together with the + toolchain identity (Clause 12, P2). A cache hit shall be equivalent to a + fresh computation. + +==== Permitted strategies + +Staged and sharded execution — rendering disjoint member subsets in separate +executions against a shared store, then composing — is an implementation +strategy. Where used, the composition shall satisfy the same determinism and +verification requirements as a single-pass build, and a store entry shall be +consumed only when the implementation can establish what produced it +(toolchain identity; see Clause 12, P2). diff --git a/sources/expressdocs-framework/sections/11-delivery-verification.adoc b/sources/expressdocs-framework/sections/11-delivery-verification.adoc new file mode 100644 index 0000000..5c00f11 --- /dev/null +++ b/sources/expressdocs-framework/sections/11-delivery-verification.adoc @@ -0,0 +1,33 @@ +[[delivery-verification]] +== Delivery verification + +Delivery is more than a build: a produced site shall be *verified* against +declared expectations before it ships. + +==== Expectations manifest + +The project (or its delivery pipeline) declares an expectations manifest — a +data document stating the shape of a correct site and its diagnostic budget, +as measured values: minimum counts for site sections, index pages, schema +documents, and attachments; an exact count where the shape is fixed; an +upper bound on missing-schema pages (zero for a complete corpus); and upper +bounds on broken links and on diagnostic rows, itemized by family. + +Expectations are *measured data with a trend*: caps are set to observed +values and ratchet downward as fixes land; they are never aspirational +ceilings invented to make a build pass. + +==== Provenance + +The build shall emit a provenance record: a canonical digest (e.g. SHA-256) +of every input and output, plus the toolchain versions. Provenance shall be +verifiable independently: recomputation from the recorded inputs either +reproduces the record or names the divergence. Signing of the provenance +record (e.g. keyless or key-based) is optional and out of scope. + +==== Diagnostics channel + +Unresolved cross-references, validation rows, and other diagnostics are +surfaced in a structured form and counted by *category and rule* — the +stable identity of a diagnostic — not by diagnostic code string (codes +migrate between tool releases; see Clause 13). diff --git a/sources/expressdocs-framework/sections/12-performance-contract.adoc b/sources/expressdocs-framework/sections/12-performance-contract.adoc new file mode 100644 index 0000000..897c28f --- /dev/null +++ b/sources/expressdocs-framework/sections/12-performance-contract.adoc @@ -0,0 +1,37 @@ +[[performance-contract]] +== Performance contract + +The framework's value proposition to corpora of thousands of schemas is +build-time behaviour, not only document expressiveness. Three requirements, +each demonstrated by existing practice on the ISO 10303 corpus. + +==== P1 — Compiled-template cache (MUST) + +An implementation compiles authoring templates once per process; rendering N +documents performs O(1) template compilations, not O(N). + +==== P2 — Content-addressed caches (MUST) + +Repeated renders of unchanged inputs are skipped. Cache keys compose input +content with toolchain versions (parser, renderer, implementation), so a hit +is equivalent to a fresh computation. A store entry consumed by a warm-skip +shall carry the identity of what produced it, and a skip shall be taken only +when that identity matches the current toolchain — a stale store degrades to +a slower build, never to stale output. Incremental and sharded strategies +(Clauses 10) live under this requirement. + +==== P3 — Byte-identical determinism (MUST) + +Identical inputs with an identical toolchain produce byte-identical outputs, +including generated identifiers (manifest node identifiers, document root +markers). Implementations shall canonicalize any platform- or run-derived +values (random identifiers, timestamps where content-fixed) so that +identical rebuilds compare byte-for-byte. This requirement is what makes +caches, golden comparisons, and delivery verification trustworthy. + +==== Rationale + +A user adopting the framework for a corpus of 4,000 schemas should expect +that the corpus does not render 4,000 times slower than one schema: parsing +and rendering costs amortize through P2, template costs amortize through P1, +and both are auditable because of P3. diff --git a/sources/expressdocs-framework/sections/13-conformance.adoc b/sources/expressdocs-framework/sections/13-conformance.adoc new file mode 100644 index 0000000..3a609f2 --- /dev/null +++ b/sources/expressdocs-framework/sections/13-conformance.adoc @@ -0,0 +1,38 @@ +[[conformance]] +== Conformance + +==== Conformance classes + +*class 1 — EXPRESSdocs project*:: a project organized per Clause 5, declared +per Clause 6, authoring content per ELF 5001, whose expectations manifest +(Clause 11) passes under a conforming implementation. + +*class 2 — conforming implementation*:: an implementation that satisfies the +template contract (Clause 7), the anchor and URN semantics (Clauses 8–9), +the build interface (Clause 10), delivery verification (Clause 11), and the +performance contract (Clause 12). + +==== Conformance corpus + +The reference conformance corpus is the EXPRESSdocs sample project +(mn-samples-expressdocs): a wg12-shaped project exercising every clause of +this document with a minutes-scale build. An implementation conforms when: + +* it builds the corpus successfully with a non-zero-exit failure mode for + each induced defect (missing document, unresolved reference, broken + expectation); +* its output for the corpus is byte-identical across repeated builds (P3); +* its expectations verification passes the corpus manifest. + +==== Diagnostic stability + +Implementations shall expose diagnostics by *category and rule*, which are +stable identifiers across releases. Diagnostic codes are display labels and +may migrate between tool releases; a migration shall be published in release +notes. Consumers shall not key behaviour on code strings. + +==== Future work + +Profiles for corpus families (e.g. ISO 10303 application-protocol +publications, their USE-FROM closure bundling) build on this framework and +are specified separately.