Simplified maintenance tools and authoring process by sthagen · Pull Request #1382 · oasis-tcs/csaf

sthagen · 2026-04-12T19:04:21Z

Maintenance and Tool Changes

migration from liitos to nide and inclusion of OASIS quality checks

Please ensure you read the three README.md files added or updated in this PR.

The diff feature of nide requires nide >= 2026.7.18 and the quality feature (acting on the OASIS rule set) requires nide >= 2026.7.19.

Please install blake3 and also install nide with the optional manifest feature.

In cases some content suffered from this large change set, I am sorry, but I did not spot. Maybe the reviewers can. Thanks.

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:

we now can do table references
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.

- merged processing for html and pdf (gfm-plus is a by-product of the html generator) - added configuration for making section reference display adaptable and steer derivation of slugs - changed sections module derives section slug and example counter mappings from prose sources - assemble is the new unified processing tool - added additional mappings in case one wants to add the section title to section refs - derived the current section mappings - rendered the user facing delivery items in gfm-plus, html, and pdf format - added clone-info action to makefile - amended makefile clean action to also remove python runtime ephemerals - patched away a regression by adding a replacement step to toccata (intermediate solution) Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

…an action Signed-off-by: Stefan Hagen <stefan@hagen.link>

tschmidtb51

Some minor comments - other than that LGTM

tschmidtb51 · 2026-04-20T16:43:00Z

@@ -636,7 +635,7 @@ <h1 id="table-of-contents">
    </h1>
    <div id="toc_container">
      <ul class="toc_list">
-        <li>1 <a href="#introduction">Introduction</a>
+        <li>1. <a href="#introduction">Introduction</a>


I think we should not end with ..

I think we should end all top level enumeration displays for sections (including appendices and annexes with a full stop, as to help the reader separate from the title text. Titles like "42 Volleyball Players" are distracting and I think bad typography. But, in case OASIS likes it differently we can always change the configurations. I still hope, that the OASIS standards will become more readable ... over time.

…fo/name targets Signed-off-by: Stefan Hagen <stefan@hagen.link>

Added distclean and amended clone-info/name targets

sthagen · 2026-05-22T16:06:02Z

Huge changes coming after Whit Monday 🤞🏽

… the OASIS admin publication checks for DPS Signed-off-by: Stefan Hagen <stefan@hagen.link>

Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen · 2026-07-18T22:52:43Z

Now, a typical complete release run with diff and quality gate checking takes on a 2020 mac mini around 9 seconds:

❯ OPEN=true make release diff quality 
2026-07-18T22:48:49.198735+00:00 INFO [nide._harvest]: first-authored-section = '# Introduction'
2026-07-18T22:48:49.199148+00:00 INFO [nide._harvest]: track-examples = True
2026-07-18T22:48:49.199180+00:00 INFO [nide._harvest]: meta-example-global-number = 4321
2026-07-18T22:48:49.307115+00:00 INFO [nide._harvest]: Loaded 226 source files → 15650 lines total
2026-07-18T22:48:49.313732+00:00 INFO [nide._section]: Identified 429 relevant section headings
2026-07-18T22:48:49.313818+00:00 INFO [nide._section]: - 13 level-1 section heading(s)
2026-07-18T22:48:49.313836+00:00 INFO [nide._section]: - 41 level-2 section heading(s)
2026-07-18T22:48:49.313855+00:00 INFO [nide._section]: - 236 level-3 section heading(s)
2026-07-18T22:48:49.313878+00:00 INFO [nide._section]: - 101 level-4 section heading(s)
2026-07-18T22:48:49.313890+00:00 INFO [nide._section]: - 38 level-5 section heading(s)
2026-07-18T22:48:49.313900+00:00 INFO [nide._section]: Section level nesting is valid.
2026-07-18T22:48:49.325029+00:00 INFO [nide._section]: Wrote 429 entries to section LUT files.
2026-07-18T22:48:49.326921+00:00 INFO [nide._example]: Example continuity valid across 234 section(s).
2026-07-18T22:48:49.331119+00:00 INFO [nide._example]: Wrote 263 example LUT entries (262 real + 1 meta at 4321).
2026-07-18T22:48:49.356762+00:00 INFO [nide._harvest]: Embedding scan complete — 0 finding(s).
2026-07-18T22:48:49.828221+00:00 INFO [nide._assemble]: Loaded 226 source files → 15582 lines total (all channels)
2026-07-18T22:48:49.932286+00:00 INFO [nide._assemble]: IR written to build/ir.json (15258 nodes)
2026-07-18T22:48:50.384537+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (15258 nodes)
2026-07-18T22:48:50.397822+00:00 INFO [nide._channel]: Rendered gfm-plus → build/gfm-plus.md (15579 lines)
Rendered user facing delivery item in markdown format:
-rw-r--r--@ 1 ruth  staff  2213700 19 Jul 00:48 ../share/csaf-v2.1-draft.ir.json
-rw-r--r--@ 1 ruth  staff   723871 19 Jul 00:48 ../share/csaf-v2.1-draft.md
2026-07-18T22:48:50.829657+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (15258 nodes)
2026-07-18T22:48:50.840981+00:00 INFO [nide._channel]: Rendered html → build/html.md (15350 lines)
2026-07-18T22:48:50.844328+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  1037761 19 Jul 00:48 ../share/csaf-v2.1-draft.html
2026-07-18T22:48:53.333070+00:00 INFO [nide._assemble]: Loaded 226 source files → 15582 lines total (all channels)
2026-07-18T22:48:53.437204+00:00 INFO [nide._assemble]: IR written to build/ir.json (15258 nodes)
2026-07-18T22:48:53.874903+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (15258 nodes)
2026-07-18T22:48:53.910034+00:00 WARNING [nide._channel]: build/typst.md line 14635: blind GFM table (no labeled caption) — typst figure counter slot consumed
2026-07-18T22:48:53.910085+00:00 WARNING [nide._channel]: build/typst.md line 14700: blind GFM table (no labeled caption) — typst figure counter slot consumed
2026-07-18T22:48:53.915627+00:00 INFO [nide._channel]: Rendered typst → build/typst.md (15597 lines)
2026-07-18T22:48:53.915838+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 — 226 files: 226 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  1037761 19 Jul 00:48 ../share/csaf-v2.1-draft.html
-rw-r--r--@ 1 ruth  staff  2213700 19 Jul 00:48 ../share/csaf-v2.1-draft.ir.json
-rw-r--r--@ 1 ruth  staff    79137 19 Jul 00:48 ../share/csaf-v2.1-draft.manifest.json
-rw-r--r--@ 1 ruth  staff   723871 19 Jul 00:48 ../share/csaf-v2.1-draft.md
-rw-r--r--@ 1 ruth  staff  3689119 19 Jul 00:48 ../share/csaf-v2.1-draft.pdf
-rw-r--r--  1 ruth  staff       95 19 Jul 00:48 ../share/csaf-v2.1-draft.pdf.blake3
-rw-r--r--  1 ruth  staff       95 19 Jul 00:48 ../share/csaf-v2.1-draft.pdf.sha256
-rw-r--r--@ 1 ruth  staff   675203 19 Jul 00:48 ../share/csaf-v2.1-draft.typ
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     ![](https://docs.oasis-open.org/templates/OASISLogo-v3.0.png)
nide quality: OASIS-RFC-2119-CITED             PASS     #RFC2119
nide quality: OASIS-RFC-8174-PAIRED            PASS     #RFC8174
nide quality: OASIS-RESID-TODO                 PASS     8473 item(s) checked
nide quality: OASIS-RESID-TBD                  PASS     8473 item(s) checked
nide quality: OASIS-RESID-FILL-IN              PASS     8473 item(s) checked
nide quality: OASIS-LINK-DEAD-LISTS            PASS     351 item(s) checked
nide quality: OASIS-LINK-DOUBLE-SLASH          PASS     318 item(s) checked
nide quality: CSAF-TITLE                       PASS     Common Security Advisory Framework Version 2.1
nide quality: CSAF-STAGE-HEADING               PASS     Committee Specification Draft 03
nide quality: CSAF-THIS-STAGE                  PASS     This stage:
nide quality: CSAF-LATEST-STAGE                PASS     Latest stage:
nide quality: CSAF-DOC-URL                     PASS     https://docs.oasis-open.org/csaf/csaf/v2.1/csd03/csaf-v2.1-csd03.md (Authoritative) \
nide quality: CSAF-TC-LINK                     PASS     https://www.oasis-open.org/committees/csaf/
nide quality: CSAF-INTRODUCTION                PASS     Introduction
nide quality: CSAF-NORMATIVE-REFS              PASS     Normative References
nide quality: CSAF-INFORMATIVE-REFS            PASS     Informative References
nide quality: CSAF-TERMINOLOGY                 PASS     Terminology
nide quality: CSAF-SCHEMA-ELEMENTS             PASS     Schema Elements
nide quality: CSAF-PROFILES                    PASS     Profiles
nide quality: CSAF-PROFILE-BASE                PASS     Profile 1: CSAF Base
nide quality: CSAF-TESTS                       PASS     Tests
nide quality: CSAF-DESIGN-CONSIDERATIONS       PASS     Design Considerations
nide quality: CSAF-ADDITIONAL-CONVENTIONS      PASS     Additional Conventions
nide quality: CSAF-ACKNOWLEDGMENTS             PASS     Acknowledgments
nide quality: CSAF-REVISION-HISTORY            PASS     Revision History
nide quality: CSAF-VEX-PROFILE                 PASS     Profile 5: VEX
nide quality: CSAF-MANDATORY-TESTS             PASS     Mandatory Tests
nide quality: CSAF-RECOMMENDED-TESTS           PASS     Recommended Tests
nide quality: CSAF-INFORMATIVE-TESTS           PASS     Informative Tests
nide quality: 0 blocker(s)  0 warning(s)  35 pass(es)  0 N/A
# took 9s

sthagen · 2026-07-18T23:01:49Z

@MColetta-OASIS I transformed the rules of your repository into data files in prose/edit/etc/ and those are validated by the nide engine. Hope you like it.

Please also see oasis-tcs/dps#201 (comment) for the IMO bad change of replacing stages with versions on the frontpage that kind of sneaked in during the tumultuous year of 2025.

sthagen · 2026-07-18T23:03:59Z

-RFC4647
-:    Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006, <https://www.rfc-editor.org/info/rfc4647/>.
-
-RFC5646
-:    Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, <https://www.rfc-editor.org/info/rfc5646/>.
-


@tschmidtb51 not sure about this (the possible loss of content added since April ...)

@sthagen Thank you for flagging this. Yes, we have content loss...

tschmidtb51

Thank you for this huge tool improvement. I've not checked it on my machine but love it already from what I know from OpenEoX.

As you discovered: There quite some content loss introduced (I guess through resolving merge conflicts 🙈 ). How do you want to handle this? Drop the merge commit and rebase your changes or should be manually correct them or do you want to provide a branch with merge conflicts and I go ahead an resolve them? 🤔 (Open for all options here - looking at you for guidance how we want to handle that.)

tschmidtb51 · 2026-07-20T12:12:59Z

-RFC4647
-:    Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006, <https://www.rfc-editor.org/info/rfc4647/>.
-
-RFC5646
-:    Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, <https://www.rfc-editor.org/info/rfc5646/>.
-


@sthagen Thank you for flagging this. Yes, we have content loss...

sthagen self-assigned this Apr 12, 2026

sthagen added tool Issue is tool related maintenance Maintenance only - no impact on specifications labels Apr 12, 2026

sthagen requested review from justmurphy, santosomar and tschmidtb51 April 12, 2026 19:11

sthagen added 2 commits April 12, 2026 22:49

Correct place for fix of regression

1da98a3

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Extended configurability, fixed regressions, and amended the make cle…

55a3d1d

…an action Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen linked an issue Apr 13, 2026 that may be closed by this pull request

Maintenance simplify tools and usage for editors #1381

Open

tschmidtb51 reviewed Apr 20, 2026

View reviewed changes

tschmidtb51 mentioned this pull request Apr 29, 2026

CSAF 2.1 CSD02 Public Feedback Resolution and Editor Revision (for TC meeting 2026-04-29) #1399

Merged

22 tasks

justmurphy approved these changes May 4, 2026

View reviewed changes

sthagen added 3 commits May 16, 2026 13:56

Simplified render-pdf and added distclean as well as amended clone-in…

092a4df

…fo/name targets Signed-off-by: Stefan Hagen <stefan@hagen.link>

Embraced ugliness to achieve a static single line python script

2a8f355

Merge pull request #1452 from oasis-tcs/makefile-enhancements

fb314c0

Added distclean and amended clone-info/name targets

sthagen marked this pull request as draft May 22, 2026 16:05

sthagen added 3 commits July 19, 2026 00:45

Migrated fully to nide including nide diff and nide quality (based on…

5abcbdb

… the OASIS admin publication checks for DPS Signed-off-by: Stefan Hagen <stefan@hagen.link>

Removed now unused artifacts / tools

9d08715

Signed-off-by: Stefan Hagen <stefan@hagen.link>

Added results of another demonstration run

a79688a

Signed-off-by: Stefan Hagen <stefan@hagen.link>

sthagen marked this pull request as ready for review July 18, 2026 23:02

sthagen commented Jul 18, 2026

View reviewed changes

sthagen mentioned this pull request Jul 19, 2026

Prepared clean structure with less gaps and aligned model representations including examples oasis-tcs/dps#201

Open

11 tasks

tschmidtb51 requested changes Jul 20, 2026

View reviewed changes

Uh oh!

Conversation

sthagen commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Maintenance and Tool Changes

Uh oh!

tschmidtb51 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tschmidtb51 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

sthagen Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sthagen commented May 22, 2026

Uh oh!

sthagen commented Jul 18, 2026

Uh oh!

sthagen commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sthagen Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

tschmidtb51 Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

tschmidtb51 left a comment

Choose a reason for hiding this comment

Uh oh!

tschmidtb51 Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sthagen commented Apr 12, 2026 •

edited

Loading

sthagen commented Jul 18, 2026 •

edited

Loading