Convert docs to AsciiDoc, localise into all five languages, add open-govpress rendering and publishing pipeline

[736-c41-2c1-e464fc974]

Summary

This turns the guidelines into a single localised AsciiDoc source tree that renders itself. Today the repository holds English-only Markdown and ODT files and publishes nothing; after this it holds 15 documents that each carry all five languages in one file (de, fr, it, rm, en), renders them to 75 PDFs through open-govpress — the Swiss federal AsciiDoc rendering tool — and publishes them to GitHub Pages with a language chooser, a per-language index, and an archive of every past build.

Live preview of the result, built from this branch by the same workflow being proposed here:
https://736-c41-2c1-e464fc974.github.io/opensource-guidelines/

The four main pieces:

1. Markdown/ODT → AsciiDoc

• Every .md and .odt document converted to .adoc and the originals removed. docs/en/ is flattened to docs/, since a per-language directory has nothing left to name once each file carries five languages.
• The four OSS checklists become [%interactive] AsciiDoc checklists — 87 static ☐ glyphs turned into real fillable PDF AcroForm widgets, not just squares that look clickable.
• Intra-repo link: targets point at .pdf, because they are followed inside the rendered PDFs next to their siblings; README.adoc keeps .adoc targets, being read on GitHub.

2. All five languages, in one file per document

• A document is :lang: on line 1, a conditional doctitle, a shared attribute header (pared back in section 8 to only what a renderer actually reads), and five whole-body ifeval:: blocks in the order en, de, fr, it, rm. open-govpress render --lang pins {lang} as a locked attribute, which drives the guards.
• TRANSLATING.md is the entry point for reviewers — it documents the file shape, the rules, the Kennzeichnung table and how to build.
• Deliberately one file, not five copies: five copies drift apart the first time someone fixes a typo in only one of them.
• The title-page Kennzeichnung is per-language and names the DTI sector per the Federal Chancellery's own pages (note the abbreviation differs: DTI de/en, TNI fr, TDT it and rm).
• publiccode.yml gains rm-CH.

3. Diagrams that are text

The 21 diagram PNGs behind 105 image:: macros were language-blind — only their alt text was ever translated, so six of them shipped German text inside the English, French, Italian and Romansh PDFs. They are now:

• [mermaid] blocks with translated labels — they diff, spell-check and are reviewable in a pull request. Authored bare, so open-govpress supplies the project palette.
• three pictures that were tables all along → real AsciiDoc tables (they translate and are announced as tables by a screen reader);
• the four-Cs gears → a generated SVG per language (tools/make-four-cs-svg.sh), so the labels are real text. The PNGs it replaces had no editable source in the repo at all.
• The document map appeared 25 times across four documents and had diverged into two disagreeing copies; it now lives once per language in docs/partials/ and is included where shown.

docs/assets/ drops from 1.45 MB of bitmaps to 233 kB.

4. Build, CI and publishing

• devenv.nix / .envrc for local work: render-docs (all languages, or render-docs de rm) produces byte-identical output to CI, including the index pages — an index reimplemented in the workflow is an index that stops matching what you see before you push.
• .github/workflows/render-docs.yml: renders the five languages as a matrix, merges them into one site, uploads PDFs as an artifact on every push and PR, and deploys to Pages on main.
• Every build is kept: pushes to main land under commits/<sha>/ (newest 10) and own the site root, v* release tags land permanently under tags/<tag>/. Backed by a site-history branch, since a Pages deployment replaces the whole site and cannot read back what is published.
• .github/workflows/lint.yml runs 13 pre-commit hooks — whitespace/EOF/symlink/executable checks, editorconfig-checker, nixfmt, yamllint, ripsecrets, shellcheck -x -o all, and a repository-local check-asciidoc that renders every document once per language (a conditional left unterminated in the Romansh block is invisible while parsing as English) and checks every cited reference key against the entries actually emitted — see section 6. typos and vale are deliberately excluded: they are English-language tools and four of five languages here are not English.
• All shell lives in tools/*.sh rather than inside Nix strings, where shellcheck and editorconfig-checker cannot see it.

5. Tables that were never tables

The document set drew 585 tables, and only 60 of them hold tabular data. The
rest are FAQ question-and-answer pairs, glossaries, reference lists, project
fact-sheets, single-cell callouts, empty write-in boxes, and tables whose only
job was to indent something. They are tables because the source came out of
Word, not because the content has columns.

That is not only untidy. tr { break-inside: avoid } makes every table row
unbreakable, and open-govpress deliberately keeps it that way: a row that breaks
mid-cell is the one fragment shape its repair logic refuses to handle, and
Paged.js then abandons the rest of the document. So a page-tall FAQ answer was
an atomic block the layout could not place, and the remedy is the construct, not
a stylesheet.

Each family moved to the construct that already described it:

• The Em002-6 FAQ — 48 tables per language whose first column held nothing
  but a localised literal Q/F/D and A/R — became [qanda.unnumbered].
  The convention was applied inconsistently, 190 of 245 questions bolded and 55
  not; the construct supplies the emphasis, so that inconsistency went with it,
  along with the legend table that documented the convention.
• Glossaries, references and the ten Annex D project fact-sheets became
  description lists. Em002-6's glossary was already one, so this finishes a
  conversion someone had started.
• The chapter-opening definition of digital sovereignty in Em002-7 became a
  sidebar, and a source attribution in Em002 became a NOTE:, which also
  deleted five hand-maintained "Source note:" prefixes.
• The four checklists lost the wrapper tables whose first column — and third,
  in Em002-2.3 — was empty in every single row.

The 75 write-in boxes were the worst of it. A [cols="1"] table holding one
empty cell is an implicit header row, so asciidoctor emitted a <thead> with a
single empty <th> and no body, and the theme paints th black. Every box in
all five languages printed as a solid black rectangle — three of them on page
2 of the English Em002-2.1. They are now field::[], a real /Tx widget you can
type into and save. Together with the checkboxes, the checklists are fillable
rather than half-fillable.

The same implicit-header defect printed "Measure 1: Implement the Practical
Guidelines…" as a heading above Measures 3, 6 and 8 in Em002. Both are gone.

60 tables stay, and each earns it: Em002-5's ten-column target-group matrix,
Em002-4's morphological box, Em002-7's sovereignty perspectives, levels, grid,
use-case classification and WTO-threshold case distinction, Em002-3's two licence
comparisons, Em002-2's document and platform tables, and Em002-1's
constellation/impact pairs. Em002-3 and Em002-7 additionally cite "Table 1" by
number in running prose in all five languages, so converting those would have
broken the reference.

No prose was changed anywhere. Five of the eight commits leave the per-language
word census byte-identical; the other three differ only by markup that was
deliberately removed, {empty} guards that render as nothing, or the field and
rows tokens of the new macro.

This needs open-govpress 0.0.12, released for it: [qanda.unnumbered],
page-break protection for terms, questions and bordered blocks, the field::[]
/Tx widget, and tables that now repeat their header and hold their column
widths across a page break. One item was asked for and did not ship — the Romansh
admonition terminology in attributes-rm.adoc still needs TERMDAT or a native
speaker before a published document relies on it.

6. Lists kept in three places, and a gate that never checked

Three lists — abbreviations, glossary, references — were maintained by hand in
Em002, Em002-6 and Em002-7, and all three had drifted apart. They now live once, in
docs/partials/{abbreviations,glossary,references}.<lang>.adoc, and each document
includes the subset it needs by tag.

The drift is the reason it was worth doing, and it was not cosmetic:

• The abbreviation lists agreed in English and in no other language.
• The glossary disagreed on five entries in English and on up to eight per
  translation.
• Of the seven reference keys appearing in more than one list, every one
  differed in title, in link form, or in both. Em002 writes link:url[text];
  Annex A writes +url+, which renders as inert text — and had lost [DigiV]'s
  URL entirely and the head noun from [BBL-CL], which began mid-phrase, "for
  Art. 9 EMOTA Blanket Exception", in all five languages.

The parse gate had never checked cross-references — and not for the reason its
own comment gave. tools/check-asciidoc.sh passed --out-file /dev/null, and
asciidoctor special-cases that path and returns before conversion, so no
conversion-stage diagnostic could reach it at any --failure-level. The comment
blamed the log level, which is the kind of wrong that stops the next person
retrying. It now converts for real, and a companion check compares cited keys
against defined ones per document per language, flattening the corpus with
asciidoctor-reducer so it applies the same tag selection that could silently drop
an entry.

That surfaced references that were broken in the published PDFs:

• Em002-7 defined [KKB-MB] while citing [KBB-MB] six times without defining
  it — 30 bracketed labels pointing at nothing across the set. One information
  sheet, one URL, one letter apart; KBB is Kompetenzzentrum Beschaffungswesen Bund
  and the sibling keys are already [KBB-KV] and [KBB-Perimap].
• BIT-KOM2023, BITCOM2024, PE1999, DigiO, OSI2019 and OSI were each
  cited with no entry anywhere, in all five languages. [OSI] deliberately became
  [Pe1999], not [OSI2024]: the sentence introduces the Open Source Definition's
  criteria, and [OSI2024] is an alphabetical licence index.

Em002-7's self-assessment grid is now fillable. It asks the reader to place a
technology on a five-by-five grid of sovereignty perspectives against maturity
levels, and gave them twenty-five empty cells — nothing to tick on paper, nothing
to click on screen. Every cell is now an interactive checkbox, 25 real /Btn
widgets per language, filled and read back through pdf.js. Its two reference tables
became description lists.

Every citation in the document set now resolves, and the gate proves it: exit 0
over the whole corpus with an empty allow-list. That has not been true before.

Needs open-govpress 0.0.15. 0.0.13 implements include::[tags=…], which the
partials depend on — 0.0.12 accepted the attribute and silently ignored it, the
dangerous direction, since stock asciidoctor honours it and a gate would go green
while the PDF shipped every entry in the file. 0.0.14 adds the three fixes in
section 7, and 0.0.15 corrects a paint defect it introduced with them: on a turned
page the app's own viewport backdrop reached the paper, because the print
stylesheet's reset was a less specific selector than the rule it meant to override
and @media adds no specificity. A quarter of every landscape page was grey. Both
defects were specified from this repo, with measurements, and both were fixed
upstream rather than worked around here.

7. Links that went nowhere, and a table that ran off the paper

Two defects that were in every published PDF and that no check could see, both
fixed by the renderer rather than by editing the documents.

Every inter-document link was dead. A relative link:em002-2.pdf[…] serialised
into the PDF as app://govpress/em002-2.pdf — the renderer's own private origin,
a scheme no PDF reader can open. 285 annotations per language, 1,425 across the
set. The fix makes a relative target pass through verbatim, so the 1,095 targets
authored here were already correct input; they were deliberately never rewritten
into absolute URLs, which would have had to be undone. Not one source line
changed and all of them now resolve — /URI (em002-1.pdf).

Em002-5's target-group matrix ran off the sheet. Ten columns against a 453.5 pt
measure: a narrow column gets 37.8 pt and Geschäftsleitung renders at 81.1 pt, so
the surplus was simply painted past the paper edge — nine words in German,
including X and (X) data cells, not merely a clipped heading. A reader could
not tell those columns were there.

The renderer now lets cell content break, and says when it had to. Em002-5 takes
the [.landscape] role instead, which turns the page that one table sits on
without changing the document type: a matrix whose headings are broken
mid-syllable is legible only in the sense that the glyphs are on the sheet. It
costs two to three pages — landscape buys width and spends height — and the
attribute sits on the table, not the document, because
:govpress-style: base-form-landscape would turn all eight pages of a prose
factsheet sideways and declare it a Basisformular, which it is not.

Both fixes were specified from this repo, with measurements, in
ai-prompt-wide-tables.md upstream.

8. Headers that repeated themselves

Two smaller cleanups to the thing every document carries at the top.

Seven of the nineteen header attributes never reached a reader.
:govpress-style: report makes open-govpress apply two attribute files of its
own before the document's header — styles/common.adoc and
styles/report.adoc, bundled in the app — and between them they already set
govpress-front-block, title-page, pdf-theme, title-logo, toc,
sectnums, toclevels, sectnumlevels and experimental. They are applied
softly, so a document's own header still outranks them; ours simply restated
values already in force, byte-identically, fifteen times over.

:toc:, :toclevels:, :sectnums: and :sectnumlevels: deliberately stay,
with a comment saying why they look redundant and are not: GitHub and GitLab
render every .adoc in the repository with plain Asciidoctor, which applies none
of open-govpress's style files, so without them the web view of the source loses
its contents list and its section numbering. The rule applied was drop what no
renderer reads, not drop what the PDF does not need. :classification: stays
too, empty and commented, so a document answers the question rather than leaving
it unasked.

The repository URL was written out 70 times. :url-repo: was defined in all
15 documents and referenced by none, while the address itself appeared literally
in four different forms, in five languages, with nothing holding them together.
All 55 body occurrences now derive from the attribute, and its value is the
repository root rather than /tree/main — the only value all four forms can be
built from, and the form open-govpress's own showcase uses. The repository being
a fork makes the owner segment the part most likely to move, which is now written
once per document instead of seventy times across them.

The four checklists, index.adoc and the README template lose the attribute
rather than gaining a reference: none of them links to the repository at all, so
defining it there would have recreated in six files exactly the unused-attribute
problem the change exists to remove.

Pre-existing content bugs fixed along the way

None of these were introduced here; they were found by converting and then reading the text in five languages.

• em002-1.md had a large duplicated content block — roughly the first third of the document repeated, in two different truncated forms. De-duplicated.
• Broken .odt checklist links across several documents (typos, trailing spaces, a missing word in the filename).
• Footnotes embedded in heading text, unsupported per the AsciiDoc docs, producing genuine duplicate HTML element IDs and a stray [N] leaking into the table of contents. Relocated to the first natural mention of the same term in the body.
• Orphaned footnotes defined but never referenced, across nearly every document — dropped rather than force-inserted.
• Defects baked into the diagram bitmaps, unfixable without an image editor: a box in Italian inside the English licence tree ("GPL o licenza permissiva"); "Verb sements must flow back?", a mangling of "Verbesserungen müssen zurückfliessen"; an Italian footnote column in the security-grounds diagram; a decision node with two branches both labelled "No", which cannot be followed; "Trnsparenz" and "Altrnativoptionen" in the sovereignty scale; and the morphological box screenshotted from PowerPoint with an object still selected, grab handles visible.
• ODT-conversion artefacts in the English text, repaired per document as each was translated — Fehler! Verweisquelle konnte nicht gefunden werden., an empty in Section ) cross-reference, "aApplication owner", "the roject is Free", "must be uthorised", "Outcomes are feedback continuously", "thus subject to the legal requirements of a?", "(at noted in Poledna/…", a doubled "in principle", the misspelt opdencode.de, an eoperation.ch link contradicting eoperations.ch in the same document, a fedlex link whose display text pointed at /de while the target was /en, and a stray literal backslash before an en-dash.
• Em002-5's figure caption described the Art. 9 EMOTA process while showing the four Cs; Em002-4's sole remaining figure was numbered 2 with no 1.
• publiccode.yml's screenshot pointed at a deleted bitmap through a /blob/ URL, which serves an HTML page rather than an image.

Left for FCh to decide, as content rather than conversion: Em002-3 annex D.5 attributes the ASTRA.EMSG road-asset application to MeteoSwiss, though both its repository and its description point to the Federal Roads Office.

Verification

• Every .adoc parses at zero errors/warnings, in all five languages, on every commit (check-asciidoc).
• render-docs renders 15 documents × 5 languages = 75 PDFs end to end via the real open-govpress CLI — no diagram falling back to a source listing, no partial rendered as a document.
• A dedicated content-completeness pass per document, comparing against the original source via git show, confirmed no content was lost — including the em002-1 de-duplication.
• All 75 title pages carry exactly the two expected Kennzeichnung lines, and the longest (fr, 61 characters) still sets on one line.
• Interactive checkboxes verified to emit real /AcroForm /Widget annotations with /TU tooltips matching each label; counts match the original glyph counts per file (25/14/9/39).
• Both workflows have been run green on this fork, including the Pages deploy, the per-commit and per-tag archive, and the v2.0 release tag.
• The table refactor holds five-language structural parity per document: a census of table fences, cols attributes, headings per level, checkbox items, footnotes, links and list terms moves by the same delta in en/de/fr/it/rm for every commit. The only cross-language differences left in the corpus are the localised abbreviation lists, which already differed before.
• A per-language word census, taken before and after with cell markup stripped, shows no word count increased anywhere — em002-2, em002-3, em002-4, em002-6 and em002-7 are byte-identical, and the only additions in the other two render as nothing.
• 585 tables become 60; 1204 rendered pages become 1073, and no document grew in any language.
• The 75 new /Tx form fields were filled in and read back with pdf.js in en and de — values return unchanged, multiline set exactly on the rows > 1 boxes — and the 435 /Btn checkboxes are unchanged at 25/14/9/39 per language.
• Every citation in the corpus resolves. tools/check-asciidoc.sh now converts rather than stopping at parse, and exits 0 in all five languages with an empty known_unresolved allow-list — a stale entry in that list is itself fatal, so it cannot outlive the problem it documents.
• The 35 lists replaced by tagged includes were checked from the rendered PDFs, not the source: all 35 come out identical before and after, entry for entry, in all five languages, with the single intended difference [KKB-MB] → [KBB-MB].
• The word census is negative in every language for every document that gained an include — text moved out — and every word with a positive delta is include-directive syntax.
• 1073 rendered pages become 1072. One document changes size: Romansh Em002-7 gains a page because Annex A got back the descriptions and URL it had lost.
• Form fields survive the rebuild: 25 /Btn in Em002-7 and 87 /Btn + 15 /Tx across the four checklists, per language.
• Zero glyphs fall outside their page in any of the 75 PDFs, against nine in the German Em002-5 before; and zero app:// URIs remain, against 285 per language. The published 0.0.15 asset was downloaded from the pinned URL and hashes to the pinned sha256, so the workflow's sha256sum -c will pass. Every landscape page of all 75 PDFs was sampled for the backdrop defect: worst coverage 0.03%, which is anti-aliasing on borders, against 25% of a turned page before the fix.

Repository settings this needs (one-time, by an admin)

Nothing here can be set from a pull request — these are repository settings, and the publish job stays red until they are in place. Merging without them is safe: the render job and the PDF artifact work regardless, only the Pages deploy fails.

1. Turn Pages on, sourced from Actions.
Settings → Pages → Build and deployment → Source: GitHub Actions (not "Deploy from a branch"). This is what creates the github-pages environment the deploy job targets.

2. Let release tags deploy, not just main.
Settings → Environments → github-pages → Deployment branches and tags. GitHub creates this environment restricted to the default branch, so the v* tag runs are rejected with a protection-rule error while main succeeds — the archive under tags/<tag>/ reaches the site-history branch but never the site. Add a rule of type Tag matching v*, so the list reads:

type	pattern
Branch	main
Tag	v*

3. Leave the default GITHUB_TOKEN permissions alone — no change needed.
Settings → Actions → General → Workflow permissions can stay on the restricted "Read repository contents and packages permissions" default. Both workflows declare permissions: contents: read at the top and raise only what a specific job needs (contents: write on collect to push the site-history branch, pages: write + id-token: write on deploy). An explicit block in the workflow overrides the repo default, so there is nothing to loosen globally.

4. Check that no ruleset covers site-history.
The publish job force-pushes a single parentless commit to a site-history branch (created on first run — no need to make it by hand). An organisation ruleset matching ** or requiring pull requests on all branches will block that push. The branch is pure derived output, re-renderable from source at any time, so exempting it costs nothing.

Nothing needs to be done for pull requests: PR runs never deploy and never push — they only upload the site artifact.

Notes for reviewers

• The open-govpress binary reference will need repointing. open-govpress itself lives at https://gitlab.com/swiss-armed-forces/cyber-command/cea/open-govpress. Since this repository is on GitHub and needs the binary available to Actions, the devenv and CI builds currently fetch a 0.0.7 Linux tarball re-hosted as a GitHub Release on this fork (open-govpress-v0.0.7), verified against a pinned SHA-256 — committing it is not an option (~112 MiB, over GitHub's 100 MB limit) and Git LFS is blocked on forks by GitHub policy. On merge, govpressUrl/govpressSha256 in devenv.nix and GOVPRESS_URL/GOVPRESS_SHA256 in .github/workflows/render-docs.yml should point at whatever the canonical publication channel turns out to be — ideally a GitLab release artifact from the upstream project, so there is no re-hosted copy to keep in sync.
• The document revision is bumped to 2.0, tagged v2.0.
• Suggested reading order: TRANSLATING.md, then one document (docs/em002-5.adoc is the smallest and was the proof of the mechanism), then tools/.

[olibrian]

Thanks for the MR. Great! @elbaer will be doing a review.