Prepared clean structure with less gaps and aligned model representations including examples#201
Prepared clean structure with less gaps and aligned model representations including examples#201sthagen wants to merge 4 commits into
Conversation
…ions including examples Signed-off-by: Stefan Hagen <stefan@hagen.link>
sthagen
added
discussion-needed
There was a problem hiding this comment.
This diagram is intentionally left outdated. It will be replaced with either a series of diagrams in parallel to the tables (kind of) or with another single diagram.
- ported some fixes from the CSDPR01 processing - clean markdown source files in prose/edit/src - configurations to steer the tools and manage the three channels gfm-plus, html, and pdf - delivery items facing users in prose/share/ - some inner document links are still work in progress (esp. around the appendixes and annexes) Signed-off-by: Stefan Hagen <stefan@hagen.link>
- migrated to nide 2026.7.14 enabling ten times faster, more reliable and portable generation of the PDF format - fixed a few nits - PDF generation is now configured per etc/nide.yaml, etc/oasis.typ, and etc/dps.typ - documentaion clean-up will be done later Signed-off-by: Stefan Hagen <stefan@hagen.link>
…liitos/etiketti/adhoc-script leftovers - in case we need footnotes these will actuallys work across formats (esp. the naviogation) - we can reduce the size of text in table cells and we can hint at columnwidths using a simple graphical like ruler argument to the columnwidths-directive - we can diff between render runs to expose the nature of changes also in binary files like PDF - we support the full dublin core attributes - we can run quality checks against OASIS rules from publication process (OASIS admins may update the rule file(s) - we only have a single frontmatter to manage - we are ten times as fast when rendering all artifacts - we now have a manifest file, checksum files for the PDF and embedded manifests - all manifests in text like formats use RFC8785 'Canonicalization Scheme (JCS)'' to prepare being able to sign them reproducibly - in case we want reproducible builds we can follow the SOURCE_DATE_EPOCH standard / convention as described in the documentation of nide and general examples per docs/SOURCE_DATE_EPOCH. Signed-off-by: Stefan Hagen <stefan@hagen.link>
|
So, with the new engine and enhanced configuration / provenance harness the whole release process takes only 3 seconds on a 2020 mac mini (this includes manifest validation): ❯ make distclean release
2026-07-19T08:42:40.935517+00:00 INFO [nide._harvest]: first-authored-section = '# Scope'
2026-07-19T08:42:40.935744+00:00 INFO [nide._harvest]: track-examples = True
2026-07-19T08:42:40.935785+00:00 INFO [nide._harvest]: meta-example-global-number = 4321
2026-07-19T08:42:40.945362+00:00 INFO [nide._harvest]: Loaded 35 source files → 2429 lines total
2026-07-19T08:42:40.946109+00:00 INFO [nide._section]: Identified 99 relevant section headings
2026-07-19T08:42:40.946149+00:00 INFO [nide._section]: - 14 level-1 section heading(s)
2026-07-19T08:42:40.946162+00:00 INFO [nide._section]: - 30 level-2 section heading(s)
2026-07-19T08:42:40.946172+00:00 INFO [nide._section]: - 7 level-3 section heading(s)
2026-07-19T08:42:40.946181+00:00 INFO [nide._section]: - 37 level-4 section heading(s)
2026-07-19T08:42:40.946189+00:00 INFO [nide._section]: - 11 level-5 section heading(s)
2026-07-19T08:42:40.946198+00:00 INFO [nide._section]: Section level nesting is valid.
2026-07-19T08:42:40.948276+00:00 INFO [nide._section]: Wrote 99 entries to section LUT files.
2026-07-19T08:42:40.948612+00:00 INFO [nide._example]: Example continuity valid across 34 section(s).
2026-07-19T08:42:40.949132+00:00 INFO [nide._example]: Wrote 35 example LUT entries (34 real + 1 meta at 4321).
2026-07-19T08:42:40.951324+00:00 INFO [nide._harvest]: Embedding scan complete — 0 finding(s).
2026-07-19T08:42:41.176756+00:00 INFO [nide._assemble]: Loaded 35 source files → 2425 lines total (all channels)
2026-07-19T08:42:41.192797+00:00 INFO [nide._assemble]: IR written to build/ir.json (2407 nodes)
2026-07-19T08:42:41.418641+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (2407 nodes)
2026-07-19T08:42:41.421973+00:00 INFO [nide._channel]: Rendered gfm-plus → build/gfm-plus.md (2424 lines)
Rendered user facing delivery item in markdown format:
-rw-r--r--@ 1 ruth staff 318741 19 Jul 10:42 ../share/prov-meta-v1.0-draft.ir.json
-rw-r--r--@ 1 ruth staff 118285 19 Jul 10:42 ../share/prov-meta-v1.0-draft.md
2026-07-19T08:42:41.659781+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (2407 nodes)
2026-07-19T08:42:41.664214+00:00 INFO [nide._channel]: Rendered html → build/html.md (2374 lines)
2026-07-19T08:42:41.665175+00:00 INFO [nide._channel]: Section records → build/section-records.json
Rendered user facing delivery item in html format:
-rw-r--r--@ 1 ruth staff 283794 19 Jul 10:42 ../share/prov-meta-v1.0-draft.html
2026-07-19T08:42:42.470270+00:00 INFO [nide._assemble]: Loaded 35 source files → 2425 lines total (all channels)
2026-07-19T08:42:42.487202+00:00 INFO [nide._assemble]: IR written to build/ir.json (2407 nodes)
2026-07-19T08:42:42.708066+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (2407 nodes)
2026-07-19T08:42:42.714729+00:00 INFO [nide._channel]: Rendered typst → build/typst.md (2441 lines)
2026-07-19T08:42:42.714959+00:00 INFO [nide._channel]: Lua filter → build/nide-columns.lua (pass to pandoc with --lua-filter)
nide manifest: written build/manifest.json
nide manifest: embedded block in build/gfm-plus.md
nide manifest: embedded block in build/html.md
nide manifest: embedded block in build/typst.md
nide validate: manifest self-hash OK
nide validate: source — 35 files: 35 OK, 0 CHANGED, 0 MISSING, 0 ADDED
nide validate: binder-hash OK
nide validate: source-state-hash OK
nide validate: outputs — 4 outputs: 4 OK, 0 CHANGED, 0 MISSING
nide validate: toolchain nide OK (2026.7.19+parent.3e973ada50)
nide validate: toolchain pandoc OK (3.10)
nide validate: toolchain typst OK (0.15.1 (unknown commit))
Release complete. Manifest verified.
-rw-r--r--@ 1 ruth staff 283794 19 Jul 10:42 ../share/prov-meta-v1.0-draft.html
-rw-r--r--@ 1 ruth staff 318741 19 Jul 10:42 ../share/prov-meta-v1.0-draft.ir.json
-rw-r--r--@ 1 ruth staff 13646 19 Jul 10:42 ../share/prov-meta-v1.0-draft.manifest.json
-rw-r--r--@ 1 ruth staff 118285 19 Jul 10:42 ../share/prov-meta-v1.0-draft.md
-rw-r--r--@ 1 ruth staff 837941 19 Jul 10:42 ../share/prov-meta-v1.0-draft.pdf
-rw-r--r-- 1 ruth staff 100 19 Jul 10:42 ../share/prov-meta-v1.0-draft.pdf.blake3
-rw-r--r-- 1 ruth staff 100 19 Jul 10:42 ../share/prov-meta-v1.0-draft.pdf.sha256
-rw-r--r--@ 1 ruth staff 102117 19 Jul 10:42 ../share/prov-meta-v1.0-draft.typ |
|
All given and known OASIS pre-publication check rules (transformed to a YAML configuration) pass: ❯ make quality
nide quality: OASIS-SCOPE PASS Scope
nide quality: OASIS-CONFORMANCE PASS Conformance
nide quality: OASIS-TECHNICAL-COMMITTEE PASS Technical Committee
nide quality: OASIS-CHAIRS PASS Chairs
nide quality: OASIS-EDITORS PASS Editors
nide quality: OASIS-ABSTRACT PASS Abstract
nide quality: OASIS-LOGO PASS 
nide quality: OASIS-RFC-2119-CITED PASS #RFC2119
nide quality: OASIS-RFC-8174-PAIRED PASS #RFC8174
nide quality: OASIS-RESID-TODO PASS 1343 item(s) checked
nide quality: OASIS-RESID-TBD PASS 1343 item(s) checked
nide quality: OASIS-RESID-FILL-IN PASS 1343 item(s) checked
nide quality: OASIS-LINK-DEAD-LISTS PASS 22 item(s) checked
nide quality: OASIS-LINK-DOUBLE-SLASH PASS 8 item(s) checked
nide quality: DPS-TITLE PASS Data Provenance Metadata Version 1.0
nide quality: DPS-STAGE-HEADING PASS Committee Specification Draft 02
nide quality: DPS-THIS-VERSION PASS This version
nide quality: DPS-LATEST-VERSION PASS Latest version
nide quality: DPS-TC-LINK PASS https://docs.oasis-open.org/dps/prov-meta/v1.0/csd01/prov-meta-v1.0-csd02.md
nide quality: DPS-DOC-URL PASS https://docs.oasis-open.org/dps/prov-meta/v1.0/csd01/prov-meta-v1.0-csd02.md
nide quality: DPS-SAFETY-SECURITY PASS Safety, Security, and Data Protection
nide quality: DPS-REFERENCES-ANNEX PASS References
nide quality: DPS-NORMATIVE-REFS PASS Normative References
nide quality: DPS-INFORMATIVE-REFS PASS Informative References
nide quality: DPS-LICENSE-ANNEX PASS License, Document Status, and Notices
nide quality: DPS-EXAMPLES-ANNEX PASS Example Instances
nide quality: DPS-ACKNOWLEDGMENTS PASS Acknowledgments
nide quality: DPS-CHANGES-APPENDIX PASS Changes From Previous Version
nide quality: DPS-KEY-WORDS-SECTION PASS Key Words
nide quality: DPS-DEFINITIONS-SECTION PASS Definitions and Acronyms
nide quality: 0 blocker(s) 0 warning(s) 30 pass(es) 0 N/A |
|
@MColetta-OASIS please kindly review these PRs froim the OASIS publication process quality perspective (similar to such tool targeting PRs in CSAF, SARIF, OpenEoX (upcoming), and MQTT(upcoming) TC repositories). I place the following statement here to make sure it finds it way. Position Statement: Restore "Stage" Vocabulary in OASIS Specification Frontmatter Submitted for consideration by the OASIS TC Process and template maintainers Background OASIS specification documents carry two independent maturity dimensions:
These two dimensions are orthogonal. A document is identified by both: "MQTT Version 5.0 Committee Specification 01" names both the content version and the process stage. The Problem The 2025 template revision replaced the frontmatter headings "This Stage", "Previous Stage", and "Latest Stage" with headings that use "Version" instead. This collapses a two-dimensional coordinate system into one axis. The consequence is ambiguity. A heading reading "This Version" conflates two distinct questions: Which content version are we talking about? and At what stage of process maturity does this document sit? Those questions have different answers and serve different readers — authors tracking process progression, legal staff assessing IPR scope, and external recipients interpreting the document's normative weight all depend on stage being clearly named. Illustrative Example: MQTT MQTT Version 3.1.1 is simultaneously an OASIS Standard and an ISO/IEC standard (ISO/IEC 20922). MQTT Version 5.0 is currently an OASIS Standard. The MQTT TC did not intend Version 5.0 to replace Version 3.1.1 — both are active, serving different deployment contexts. Each of these version trains has its own stage progression. An "MQTT v3.1.1 CSD01" has different normative standing than an "MQTT v3.1.1 OS", and both of those are distinct from anything in the v5.0 train. If frontmatter headings say "This Version" rather than "This Stage", it becomes genuinely unclear what is being asserted: the content version identity or the maturity stage of the document in hand. ISO Alignment OASIS Open is a recognized ANSI-accredited standards body and an accepted submitter to ISO. ISO's own vocabulary for this dimension is well-established: the International Harmonized Stage Codes (https://www.iso.org/stage-codes.html) provide a global taxonomy of document maturity states. ISO does not conflate stage and version; neither should we. When an OASIS Standard is submitted for adoption as an ISO standard, the OASIS stage vocabulary must map cleanly to ISO stage codes. "OS" maps; "This Version" does not. Removing stage terminology from OASIS templates creates unnecessary friction at the ISO submission boundary — precisely the point where clear stage designation becomes most consequential. Proposal Restore the "This Stage", "Previous Stage", and "Latest Stage" headings to the OASIS specification frontmatter template. These headings should name the document's current process maturity state, distinct from the version identifier that appears in the document title and title block. Retaining "version" vocabulary for the content dimension and "stage" vocabulary for the process dimension preserves the precision that the TC Process itself depends on, aligns with ISO terminology, and avoids introducing a false equivalence between two concepts that are independently important to authors, reviewers, legal staff, and downstream standard bodies. |
3 participants
The editors worked on a clean source version of the prov-meta spec with less gaps, more consistency (JSON was base, tables provided enumerations), and better example inclusion.
Structural changes:
The user facing delivery items derived from the files in the prose/edit/src subtree are placed in prose/share/. These are the gfm-plus, html, and pdf variants that would end up at https://docs.oasis-open.org/dps/prov-meta/
Before merge you can still access these files directlsy (no difference views but the full GitHub default view for the formats) by visiting the incoming "source" branch at https://github.com/oasis-tcs/dps/tree/prov-meta-1-0-ng-structure/prov-meta-1.0/prose/share
When the setup is complete (with all internal linking working), I will activate the PR as ready for review and merge.
I did invest quite some time in the documentation of nide and you are welcome to visit the man page, quickstart, tutorial, or the example page(s) but in short here are the main additional tool changes for enhancement and ease of collaboration: