xml2rfc 4.x vs 2.x: What Changed and How It Affects Your RFC

Getting Started with xml2rfc: Tools, Tips, and Best Practicesxml2rfc is the canonical tool for writing Internet-Drafts and RFCs in XML format defined by the IETF. It converts structured XML source into publication-quality output (text, HTML, and PDF) and enforces the rules and boilerplate required by IETF document formats. This guide walks you through the ecosystem, the practical workflow, useful tools, common pitfalls, and recommendations to produce clean, compliant RFCs and drafts.

What is xml2rfc and why use it?

xml2rfc takes an XML representation of a draft or RFC and generates the formats required by the IETF and by readers. The XML schema captures semantic structure (title, authors, sections, references, examples, citations) so that presentation and conformance checks can be applied consistently. Using xml2rfc provides:

Consistent, standards-compliant output across text/HTML/PDF.
Semantic clarity—content is structured, not just formatted.
Validation that helps catch boilerplate and normative issues early.
Automation-friendly pipeline for CI/CD and reproducible builds.

Versions and formats: xml2rfc 2 vs 3 vs 4

Over time xml2rfc has evolved. The important versions to know:

xml2rfc 2 (classic): older, used with the RFC 2026-era formatting and templates. Some older documents still use this tool.
xml2rfc 3: introduced improved syntax and features; less commonly used today.
xml2rfc 4 (current): redesigned with a modern XML vocabulary and richer semantic features; preferred for new drafts.

When starting a new document, prefer xml2rfc 4. It supports current IETF conventions and integrates well with modern tools.

Install and set up

Basic installation options:

Python package (recommended for most users):
- Install xml2rfc via pip: pip install xml2rfc (ensures python environment isolation with venv/virtualenv).
Distribution packages:
- Some Linux distros provide xml2rfc packages via their package managers; versions may lag behind pip.
Docker:
- Use an official or community Docker image for reproducible environments in CI.

After installation, verify with:

xml2rfc --version

If using xml2rfc 4, you can generate outputs like:

xml2rfc draft.xml --html --text --pdf

(Exact CLI flags may vary by version; check xml2rfc --help.)

XML source structure — the essentials

A typical xml2rfc 4 document uses a straightforward hierarchy. Key elements include:

<rfc> root element with attributes (e.g., submissionType, ipr)
<front>: metadata—title, short-name, authors, dates, and abstract
<middle>: the main body—sections (<section>), subsections, figures, examples, lists
<back>: references, acknowledgements, author address blocks

Example (minimal skeleton):

<?xml version="1.0" encoding="utf-8"?> <rfc submissionType="internet-draft" ipr="trust200902">   <front>     <title>My Draft Title</title>     <author initials="A." surname="Smith">       <organization>Example Corp</organization>       <address>         <email>[email protected]</email>       </address>     </author>     <date year="2025" month="August" />     <area>Applications and Real-Time</area>     <abstract>Short description of the draft.</abstract>   </front>   <middle>     <section title="Introduction" anchor="intro">       <t>Paragraph text goes here.</t>     </section>   </middle>   <back>     <references>       <eref type="rfc" target="RFC2119">RFC 2119</eref>     </references>   </back> </rfc>

Notes:

Use <t> for regular paragraph text inside sections.
Use anchor attributes for stable cross-references.
Keep metadata accurate—some fields affect generated boilerplate.

Writing content: semantics over presentation

Treat xml2rfc XML as semantic markup, not a visual stylesheet. Use the correct elements for intent:

Use <title>, <section>, <t> (text), <figure>, <example>, <table>, <sourcecode> where appropriate.
Mark normative vs informative references properly (<reference> vs <reference type="informative"> or <eref type="rfc" normative="true">).
Use <abbrev> for abbreviations if you want later tooling support to expand or index them.

Avoid embedding presentation tricks (spaces, manual line breaks) into source; let xml2rfc handle layout.

References and citation best practices

References are common sources of validation errors. Tips:

Use <references> and <eref> or <reference> elements in <back>.
Distinguish normative and informative references.
For normative RFC references, use type="rfc" and the target attribute (e.g., target="RFC2119").
Provide complete bibliographic data for non-RFC references.
Keep cross-reference anchors consistent when referencing internal sections: use <xref> or link using anchor values.

Example:

<references>   <reference anchor="rfc2119" target="RFC2119" type="rfc">     <front>       <title>Key words for use in RFCs to Indicate Requirement Levels</title>       <author initials="S." surname="Bradner"/>       <date year="1997" month="March"/>     </front>   </reference> </references>

Common pitfalls and how to avoid them

Missing required front-matter fields (title, authors, date) — validate early.
Incorrect element nesting or typos in element names — use an XML-aware editor or validator.
Mixing xml2rfc versions’ vocabularies — decide on a version and stick to it.
Treating xml as visual markup—don’t hard-code line breaks or visual layout.
Unresolved references or bad anchors — run validation and fix anchor names.

Use xml2rfc --validate (or equivalent) to catch issues before submission.

Editor tooling and helpers

Use tools that improve productivity:

XML-aware editors: VS Code, Sublime, Emacs, Vim — add XML plugins for syntax highlighting and linting.
XML schema/DTD/RELAX NG validation: configure your editor to validate against the xml2rfc schema.
Snippets and templates: create a project template with your typical front/back sections, author blocks, and commonly used examples.
Pre-commit hooks and formatters: serialize consistent formatting, though formatting is secondary to semantic correctness.

VS Code tip: install XML extension and configure the xml2rfc schema for auto-complete and validation.

Testing and generating outputs

Generate multiple formats to check for issues:

Plain text: required for IETF submissions.
HTML: good for quick visual inspection.
PDF: for reviewers who prefer print-like layout.

Automate generation in a Makefile or CI pipeline:

xml2rfc draft.xml --text --html --pdf

Include a validation step:

xml2rfc draft.xml --check

In CI (GitHub Actions/GitLab CI), run xml2rfc in a step and fail the job if validation or generation fails.

Automating with CI/CD

A CI pipeline enforces quality and reproducibility. Example steps:

Install xml2rfc (pip or Docker).
Run schema validation.
Generate text/html/pdf outputs.
Run linters (custom checks for style or required sections).
Attach artifacts (generated drafts) to builds or releases.

Use Docker for consistent environments across contributors.

Collaboration tips

Keep xml source under version control (Git). Commit small logical changes.
Use pull requests to review content; diffs in XML are verbose—review by generated HTML when content is large.
Maintain contributor guidelines and a template repository for new drafts.
For multi-author documents, maintain a single source of truth and avoid divergent branches for long-lived drafts.

Examples and advanced features

Inline XML examples and source code: use <sourcecode> with language attribute.
Complex tables: prefer semantic table elements and avoid forcing visual width via spaces.
Conditional content and metadata: xml2rfc supports structured metadata that downstream tools can use for indexing or automation.

Accessibility and internationalization

Use semantic elements so generated HTML and text are more accessible.
Provide alternative text for figures where practical.
Use Unicode and declare encoding (UTF-8) — xml2rfc handles UTF-8 cleanly.

When to deviate from defaults

Defaults are sensible for most drafts. Consider customizing only when:

You need a specific presentation style for non-IETF internal distribution (but keep the canonical xml source).
You’re generating additional derivative outputs (slides, internal docs) — generate those from the same source via custom transformations.

Prefer extensions and transformations that preserve the canonical XML.

Resources and references

Official xml2rfc documentation and schema (consult the version you use).
Example RFC/XML repositories on GitHub for real-world patterns.
IETF authoring guidelines and boilerplate examples.

Quick checklist before submission

Front matter complete and accurate (title, authors, date).
Document validates with xml2rfc schema for your chosen version.
References are complete and marked normative/informative correctly.
Generated text/HTML/PDF produced and inspected.
CI validation present (optional but recommended).

Final note: treating xml2rfc as the canonical, semantic source of truth pays off — you get consistent output, easier collaboration, and fewer headaches at submission time.