Skip to content

site: port the archived pubid-*/README content — ISO/IEC/PLATEAU ports, 6 missing flavor pages, construction guide - #20

Merged
ronaldtse merged 3 commits into
mainfrom
docs/port-flavor-readmes
Nov 8, 2026
Merged

ronaldtse merged 3 commits into
mainfrom
docs/port-flavor-readmes

Conversation

@ronaldtse

@ronaldtse ronaldtse commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Site-side half of the archived-README port (gem-side half: pubid/pubid#679). The website was missing six flavors the pubid 2 registry carries, and the usage narrative the archived per-gem READMEs held was absent from the ISO/IEC/PLATEAU publisher pages.

New publisher pages: doi, evs, gb, isbn, omg, un

Built from the monogem's identifier classes and pass fixtures. Every output value and syntax claim was verified by parsing the example with the gem:

  • bare ISBN forms (0-306-40615-2, 9783161484100) parse at the flavor entry point with hyphenation preserved as given — the outputs state that exactly
  • bare DOI names / DOI: / resolver URLs all render canonical doi:… at the flavor entry point (global prefix routing requires the doi: token)
  • GB: mandate letters (T/Z/none), body codes (GB/JB/GBn/T/{ORG}) as identity, em-dash year form normalizing to ASCII, (all parts)
  • EVS adoption chain (EVS-EN ISO/IEC …) with slash supplements

Publisher.logo becomes optional (logo?: string) — the hero already rendered a two-letter badge fallback for missing assets; six of the new flavors have no logo file yet. src/data/__tests__/registry.spec.ts updates the exact publisher count 38 → 44 with the rationale in a comment.

3GPP deliberately not added: the site already carries a full 3GPP page at flavor key tgpp (src/data/flavors/tgpp.ts) — an earlier filename-based audit mistook the gem's 3gpp registry key for a gap.

ISO page

  • New Rendering Styles section (the styles field the FlavorPage template already renders): the live v2 rendering options — canonical detection, lang_single: (short stage + single-letter language), stage_format_long: (long Amd/DCor/FDCor faces), with_date: (undated), with_edition: — with verified examples. The v1 format: :ref_num_short-symbol API is not a v2 API.
  • Amendment docType: the DAM/FDAM typed stages and the parse-only historic spellings DAmd/FDAmd with the verified canonicalization example.
  • Corrigendum docType: DCor/FDCor long faces vs DCOR/FDCOR short faces; DIS Cor/FDIS Cor/FCOR legacy spellings canonicalize.
  • Typed Stage component: lists the supplement stages.

IEC page

  • iecee_trf docType now spells out the full TRF pattern from the archived pubid-iec README: & part join (,/; normalized), version letters with string sub-versions (F_II), _EMC/_PS/_SOF test types — verified examples.
  • New iecex_trf docType: the _ (official pattern) vs v (IEC Webstore) separator, std-edition, A_DS-style sub-versions — verified examples.

PLATEAU page

The Handbook #11 edition-split rule (editions 1–3: (民間活用編) was #6, (公共活用編) was #4; combined only from edition 4) documented in the Handbook docType and syntaxNotes, with the six verified rewrite examples — the rule lives in the gem's data/plateau/update_codes.yaml and was previously undocumented on both sides.

Library

New Constructing Identifiers page (/library/constructing-identifiers, linked from the library index): the v2 replacement for the v1 Identifier.create — typed .new, the unknown-key refusal and scalar coercion, Pubid.from_hash, supplement-with-base (ISO/IEC/IEEE), copublishers, typed stages via Pubid::Iso.locate_stage. All snippets verified against the gem.

Verification

  • astro check: 0 errors, 0 warnings
  • vitest run: 429 passed
  • astro build: 349 pages; all six new publisher pages, the IEEE AIEE/IRE docTypes, and the library page generate
  • lychee run locally over the new and modified pages: the only failing link is the pre-existing header link github.com/pubid/pubid.github.io (a transient 504 present on every page including untouched ones); the content this PR adds introduces zero failing links
  • Data-model sources: pubid/pubid lib/ and spec/fixtures/ on the gem's current main

… ports, 6 missing flavor pages, construction guide

The website was missing six flavors the pubid 2 registry carries (doi, evs,
gb, isbn, omg, un) and the usage narrative the archived per-gem READMEs held:
the ISO format options, the IEC TRF grammars, and the PLATEAU Handbook #11
edition split.

- New publisher pages: doi, evs, gb, isbn, omg, un — built from the monogem's
  identifier classes and pass fixtures, every example verified by parsing it
  with the gem (bare ISBN/DOI forms noted as flavor-entry-point parses;
  ISBN hyphenation preserved as given). `Publisher.logo` becomes optional so
  a page renders the two-letter badge until a logo asset exists.
- ISO page: a Rendering Styles section documents the live rendering options
  (lang_single, stage_format_long, with_date, with_edition — the v1
  `format:`-symbol API is not a v2 API); the amendment/corrigendum docTypes
  now carry the DAM/FDAM and DCor/FDCor stage rules with verified
  normalization examples; the Typed Stage component lists the supplement
  stages.
- IEC page: the iecee_trf docType spells out the full TRF pattern (& join,
  F_II-style sub-versions, _EMC/_PS/_SOF test types) and a new iecex_trf
  docType documents the `_`/`v` separator and std-edition with verified
  examples.
- PLATEAU page: the Handbook #11 edition-split rule (#6/#4 for editions
  1-3) documented with verified rewrite examples.
- Library: a Constructing Identifiers page — the v2 replacement for the v1
  `Identifier.create` (typed `.new`, from_hash, supplement-with-base,
  copublishers, stages) — linked from the library index.
- The publisher-count spec updates 38 -> 44 for the six new pages; 3GPP
  already had a page (flavor key "tgpp").

Sources: pubid/pubid-iso, pubid-iec, pubid-plateau README.adoc (archived);
the pubid gem's lib/ and spec/fixtures/ as the correctness authority.
@ronaldtse

Copy link
Copy Markdown
Contributor Author

CI status note: the two Build & Test failures on this PR are environmental, not content.

  1. Runs 42470149906 (10:08) and its 10:20 failed-jobs rerun die inside lychee-action setup, downloading lycheeverse/lychee v0.24.2 — the release asset returns 504. At the same time https://github.com/pubid/... returns 504 from outside CI as well (verified with curl from a local machine), so this is a GitHub-side outage window, not the action version or the workflow.

  2. On the run where the download did succeed (42470635706, 10:15), the actual link check ran and produced exactly 4 errors, all the same pre-existing link https://github.com/pubid (504) on dist/about, dist/index, dist/publishers/ashrae, dist/specs — none of which this PR touches; the header/footer link exists on every page of main. The pages this PR adds or modifies (doi, evs, gb, isbn, omg, un, ieee, iso, iec, plateau, library/constructing-identifiers) produced zero link-check errors in that same run, and a local lychee pass over exactly those pages agrees (235 OK / 10 errors, all the same pre-existing 504).

The workflow, lychee.toml and .lycheeignore are untouched by this branch. Rerun Build & Test once the GitHub 504 window passes — no code change is expected to be needed.

@ronaldtse

Copy link
Copy Markdown
Contributor Author

Follow-up on the CI note: the incident has partially cleared and the check now runs further — the current failure is a single external bot-block, not this PR.

  • The lychee binary now downloads; the link check runs.
  • The remaining error is [403] https://www.ashrae.org/ on dist/publishers/ashrae/index.html — a page this PR does not touch (ashrae.ts unchanged; the link is the publisher's own website field, present on main). ashrae.org is flapping on bot protection: it returned 200 to the same user-agent from a local machine ~40 minutes before the CI run, and 403 now from that same machine. Earlier runs in the same window failed on GitHub's own 504s (github.com/pubid, the lychee release asset) — all environmental.
  • The pages this PR adds or modifies (doi, evs, gb, isbn, omg, un, ieee, iso, iec, plateau, library/constructing-identifiers) still produce zero link-check errors.

Nothing in this PR needs changing for CI to go green; a rerun once ashrae.org stops challenging the checker is expected to pass. If the 403 proves persistent rather than flapping, the house convention would be a commented entry in .lycheeignore — left to the maintainer since ashrae.ts is outside this PR's scope.

@ronaldtse
ronaldtse merged commit c1b0612 into main Nov 8, 2026
0 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant