feat: unified drafts/ structure with PDF outputs for ACT and ECT

Both drafts now live in workspace/drafts/ as siblings:
  drafts/
  ├── act/                       (ACT -01, native to parent repo)
  │   ├── draft-nennemann-act-01.md     kramdown-rfc source
  │   ├── draft-nennemann-act-01.{xml,txt,html,pdf}
  │   ├── .refcache/             bibxml cache
  │   └── build.sh
  ├── ietf-wimse-ect/            (ECT -02, submodule, PDF added)
  │   └── ...
  └── README-pdf.md              PDF toolchain docs

ACT kramdown-rfc conversion:
- full YAML frontmatter (title, author, refs)
- section structure matches kramdown-rfc conventions
- {{REF}} citation syntax, auto-numbered sections
- references auto-built from normative/informative blocks
- removed manual TOC (kramdown-rfc generates)
- builds cleanly: 133K XML, 89K TXT, 208K HTML, 167K PDF

PDF toolchain:
- xml2rfc --pdf via weasyprint<60 + pydyf<0.10 injected into xml2rfc pipx venv
- both build.sh scripts now produce PDF as Step 4
- README-pdf.md documents the setup for new machines

Submodule: bump ietf-wimse-ect pointer for build.sh PDF step
This commit is contained in:
2026-04-12 14:01:57 +02:00
parent 37859beef6
commit 56f2ce669c
20 changed files with 9749 additions and 482 deletions

View File

@@ -0,0 +1,67 @@
# PDF Generation for IETF Drafts
## Status
`xml2rfc --pdf` is wired up on this machine. PDFs are generated automatically
as part of `build.sh` in each draft directory.
## How it works
`xml2rfc` is installed via `pipx` in its own venv
(`/home/c/.local/share/pipx/venvs/xml2rfc/`). The `--pdf` switch requires
several extra dependencies that had to be injected into that venv:
```bash
pipx inject xml2rfc "weasyprint<60" pycairo pangocffi
/home/c/.local/share/pipx/venvs/xml2rfc/bin/python -m pip install "pydyf<0.10"
```
Version pins matter:
- `weasyprint 59.x` — xml2rfc's `--pdf` code path calls weasyprint's
`write_pdf(target, stylesheets=[...], presentational_hints=True)`.
Newer weasyprint (60+) changes the signature.
- `pydyf <0.10` — weasyprint 59 calls `pydyf.PDF(version, identifier)` with
two positional args. pydyf 0.10+ removed those.
System libs used via ctypes: `pango`, `pangocairo`, `cairo`, `harfbuzz`
(all already present via Fedora packages).
Fonts: xml2rfc uses Noto + Roboto Mono embedded in the weasyprint output.
Not installed system-wide but weasyprint fonttools handles them.
## Build step (pattern for build.sh)
After the HTML step, add:
```bash
# Step 4: XML -> PDF
echo "Generating PDF output..."
if "$XML2RFC" "$DIR/$DRAFT.xml" --pdf --quiet 2>/dev/null; then
PDF_OK=1
else
echo " xml2rfc --pdf failed; falling back to weasyprint on HTML"
if command -v weasyprint >/dev/null 2>&1; then
weasyprint "$DIR/$DRAFT.html" "$DIR/$DRAFT.pdf" >/dev/null 2>&1 \
&& PDF_OK=1 || PDF_OK=0
else
PDF_OK=0
fi
fi
```
## Verification
`ietf-wimse-ect/draft-nennemann-wimse-ect-02.pdf` — 178 KB, generated via
`xml2rfc --pdf` (IETF-idiomatic layout with Noto fonts, title page,
bookmarks, and proper TOC). The fallback `weasyprint html->pdf` produces a
172 KB PDF that works but renders the html2rfc template instead of the
official IETF print layout; use it only if xml2rfc --pdf is unavailable.
## Reinstallation checklist (on a new machine)
1. `pipx install xml2rfc`
2. `pipx inject xml2rfc "weasyprint<60" pycairo pangocffi`
3. `/home/c/.local/share/pipx/venvs/xml2rfc/bin/python -m pip install "pydyf<0.10"`
4. Install system libs: `dnf install pango cairo harfbuzz` (Fedora) or
`apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz0b` (Debian)
5. Test: `xml2rfc some-draft.xml --pdf`

View File

@@ -0,0 +1,35 @@
<?xml version="1.0" encoding="UTF-8"?>
<reference anchor="I-D.ietf-scitt-architecture" target="https://datatracker.ietf.org/doc/html/draft-ietf-scitt-architecture-22">
<front>
<title>An Architecture for Trustworthy and Transparent Digital Supply Chains</title>
<author initials="H." surname="Birkholz" fullname="Henk Birkholz">
<organization>Fraunhofer SIT</organization>
</author>
<author initials="A." surname="Delignat-Lavaud" fullname="Antoine Delignat-Lavaud">
<organization>Microsoft Research</organization>
</author>
<author initials="C." surname="Fournet" fullname="Cedric Fournet">
<organization>Microsoft Research</organization>
</author>
<author initials="Y." surname="Deshpande" fullname="Yogesh Deshpande">
<organization>ARM</organization>
</author>
<author initials="S." surname="Lasker" fullname="Steve Lasker">
</author>
<date month="October" day="10" year="2025" />
<abstract>
<t> Traceability in supply chains is a growing security concern. While
verifiable data structures have addressed specific issues, such as
equivocation over digital certificates, they lack a universal
architecture for all supply chains. This document defines such an
architecture for single-issuer signed statement transparency. It
ensures extensibility, interoperability between different
transparency services, and compliance with various auditing
procedures and regulatory requirements.
</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-scitt-architecture-22" />
</reference>

View File

@@ -0,0 +1,13 @@
<reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author fullname="S. Bradner" initials="S." surname="Bradner"/>
<date month="March" year="1997"/>
<abstract>
<t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<seriesInfo name="DOI" value="10.17487/RFC2119"/>
</reference>

View File

@@ -0,0 +1,14 @@
<reference anchor="RFC7009" target="https://www.rfc-editor.org/info/rfc7009">
<front>
<title>OAuth 2.0 Token Revocation</title>
<author fullname="T. Lodderstedt" initials="T." role="editor" surname="Lodderstedt"/>
<author fullname="S. Dronia" initials="S." surname="Dronia"/>
<author fullname="M. Scurtescu" initials="M." surname="Scurtescu"/>
<date month="August" year="2013"/>
<abstract>
<t>This document proposes an additional endpoint for OAuth authorization servers, which allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. This allows the authorization server to clean up security credentials. A revocation request will invalidate the actual token and, if applicable, other tokens based on the same authorization grant.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7009"/>
<seriesInfo name="DOI" value="10.17487/RFC7009"/>
</reference>

View File

@@ -0,0 +1,14 @@
<reference anchor="RFC7515" target="https://www.rfc-editor.org/info/rfc7515">
<front>
<title>JSON Web Signature (JWS)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<author fullname="J. Bradley" initials="J." surname="Bradley"/>
<author fullname="N. Sakimura" initials="N." surname="Sakimura"/>
<date month="May" year="2015"/>
<abstract>
<t>JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7515"/>
<seriesInfo name="DOI" value="10.17487/RFC7515"/>
</reference>

View File

@@ -0,0 +1,12 @@
<reference anchor="RFC7517" target="https://www.rfc-editor.org/info/rfc7517">
<front>
<title>JSON Web Key (JWK)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<date month="May" year="2015"/>
<abstract>
<t>A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7517"/>
<seriesInfo name="DOI" value="10.17487/RFC7517"/>
</reference>

View File

@@ -0,0 +1,12 @@
<reference anchor="RFC7518" target="https://www.rfc-editor.org/info/rfc7518">
<front>
<title>JSON Web Algorithms (JWA)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<date month="May" year="2015"/>
<abstract>
<t>This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7518"/>
<seriesInfo name="DOI" value="10.17487/RFC7518"/>
</reference>

View File

@@ -0,0 +1,14 @@
<reference anchor="RFC7519" target="https://www.rfc-editor.org/info/rfc7519">
<front>
<title>JSON Web Token (JWT)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<author fullname="J. Bradley" initials="J." surname="Bradley"/>
<author fullname="N. Sakimura" initials="N." surname="Sakimura"/>
<date month="May" year="2015"/>
<abstract>
<t>JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7519"/>
<seriesInfo name="DOI" value="10.17487/RFC7519"/>
</reference>

View File

@@ -0,0 +1,12 @@
<reference anchor="RFC8037" target="https://www.rfc-editor.org/info/rfc8037">
<front>
<title>CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)</title>
<author fullname="I. Liusvaara" initials="I." surname="Liusvaara"/>
<date month="January" year="2017"/>
<abstract>
<t>This document defines how to use the Diffie-Hellman algorithms "X25519" and "X448" as well as the signature algorithms "Ed25519" and "Ed448" from the IRTF CFRG elliptic curves work in JSON Object Signing and Encryption (JOSE).</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8037"/>
<seriesInfo name="DOI" value="10.17487/RFC8037"/>
</reference>

View File

@@ -0,0 +1,13 @@
<reference anchor="RFC8174" target="https://www.rfc-editor.org/info/rfc8174">
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author fullname="B. Leiba" initials="B." surname="Leiba"/>
<date month="May" year="2017"/>
<abstract>
<t>RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="8174"/>
<seriesInfo name="DOI" value="10.17487/RFC8174"/>
</reference>

View File

@@ -0,0 +1,16 @@
<reference anchor="RFC8693" target="https://www.rfc-editor.org/info/rfc8693">
<front>
<title>OAuth 2.0 Token Exchange</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<author fullname="A. Nadalin" initials="A." surname="Nadalin"/>
<author fullname="B. Campbell" initials="B." role="editor" surname="Campbell"/>
<author fullname="J. Bradley" initials="J." surname="Bradley"/>
<author fullname="C. Mortimore" initials="C." surname="Mortimore"/>
<date month="January" year="2020"/>
<abstract>
<t>This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8693"/>
<seriesInfo name="DOI" value="10.17487/RFC8693"/>
</reference>

View File

@@ -0,0 +1,16 @@
<reference anchor="RFC9110" target="https://www.rfc-editor.org/info/rfc9110">
<front>
<title>HTTP Semantics</title>
<author fullname="R. Fielding" initials="R." role="editor" surname="Fielding"/>
<author fullname="M. Nottingham" initials="M." role="editor" surname="Nottingham"/>
<author fullname="J. Reschke" initials="J." role="editor" surname="Reschke"/>
<date month="June" year="2022"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes.</t>
<t>This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230.</t>
</abstract>
</front>
<seriesInfo name="STD" value="97"/>
<seriesInfo name="RFC" value="9110"/>
<seriesInfo name="DOI" value="10.17487/RFC9110"/>
</reference>

View File

@@ -0,0 +1,24 @@
<reference anchor="RFC9562" target="https://www.rfc-editor.org/info/rfc9562">
<front>
<title>Universally Unique IDentifiers (UUIDs)</title>
<author fullname="K. Davis" initials="K." surname="Davis"/>
<author fullname="B. Peabody" initials="B." surname="Peabody"/>
<author fullname="P. Leach" initials="P." surname="Leach"/>
<date month="May" year="2024"/>
<abstract>
<t>This specification defines UUIDs (Universally Unique IDentifiers) --
also known as GUIDs (Globally Unique IDentifiers) -- and a Uniform
Resource Name namespace for UUIDs. A UUID is 128 bits long and is
intended to guarantee uniqueness across space and time. UUIDs were
originally used in the Apollo Network Computing System (NCS), later
in the Open Software Foundation's (OSF's) Distributed Computing
Environment (DCE), and then in Microsoft Windows platforms.</t>
<t>This specification is derived from the OSF DCE specification with the
kind permission of the OSF (now known as "The Open Group"). Information from earlier versions of the OSF DCE specification have
been incorporated into this document. This document obsoletes RFC
4122.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9562"/>
<seriesInfo name="DOI" value="10.17487/RFC9562"/>
</reference>

69
workspace/drafts/act/build.sh Executable file
View File

@@ -0,0 +1,69 @@
#!/bin/bash
set -e
DIR="$(cd "$(dirname "$0")" && pwd)"
SRC="$DIR/draft-nennemann-act-01.md"
# Extract docname from YAML front matter
DRAFT=$(grep '^docname:' "$SRC" | head -1 | awk '{print $2}')
if [ -z "$DRAFT" ]; then
echo "Error: could not extract docname from $SRC"
exit 1
fi
# Tool paths
KRAMDOWN="$(which kramdown-rfc2629 2>/dev/null)"
XML2RFC="$(which xml2rfc 2>/dev/null)"
if [ -z "$KRAMDOWN" ]; then
echo "Error: kramdown-rfc2629 not found. Install with: gem install kramdown-rfc2629"
exit 1
fi
if [ -z "$XML2RFC" ]; then
echo "Error: xml2rfc not found. Install with: pip install xml2rfc"
exit 1
fi
export PYTHONWARNINGS="ignore::UserWarning"
echo "Building: $DRAFT"
echo "Using kramdown-rfc2629: $KRAMDOWN"
echo "Using xml2rfc: $XML2RFC"
echo ""
# Step 1: Markdown -> XML
echo "Converting markdown to XML..."
"$KRAMDOWN" "$SRC" > "$DIR/$DRAFT.xml"
# Step 2: XML -> TXT
echo "Generating text output..."
"$XML2RFC" "$DIR/$DRAFT.xml" --text --quiet 2>/dev/null
# Step 3: XML -> HTML
echo "Generating HTML output..."
"$XML2RFC" "$DIR/$DRAFT.xml" --html --quiet 2>/dev/null
# Step 4: XML -> PDF (requires weasyprint + pangocffi + pycairo injected into xml2rfc venv
# and pydyf<0.10 pinned; see /home/c/projects/research.ietf/workspace/drafts/README-pdf.md)
echo "Generating PDF output..."
if "$XML2RFC" "$DIR/$DRAFT.xml" --pdf --quiet 2>/dev/null; then
PDF_OK=1
else
echo " xml2rfc --pdf failed; falling back to weasyprint on HTML"
if command -v weasyprint >/dev/null 2>&1; then
weasyprint "$DIR/$DRAFT.html" "$DIR/$DRAFT.pdf" >/dev/null 2>&1 && PDF_OK=1 || PDF_OK=0
else
PDF_OK=0
fi
fi
echo ""
echo "Build complete:"
echo " $DRAFT.xml (submit this to datatracker)"
echo " $DRAFT.txt"
echo " $DRAFT.html"
if [ "${PDF_OK:-0}" = "1" ]; then
echo " $DRAFT.pdf"
else
echo " (PDF generation skipped — missing deps)"
fi

File diff suppressed because it is too large Load Diff

Binary file not shown.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

Submodule workspace/drafts/ietf-wimse-ect updated: d47f041265...3d01cb32b6