Migrating SGML Documents to XML: A Practical Guide

SGML is old. Your content does not have to be.

Organizations still encounter SGML repositories whose editing and publishing environments have become difficult to maintain. The content, however, may remain highly structured and valuable.

XML was designed as a simplified subset of SGML. That relationship provides a practical migration path, provided that the source is parsed as SGML rather than treated as malformed XML.

This article explains a controlled workflow using the original DTDs, catalogs and entities together with James Clark's SGML tooling as continued in OpenSP.

Migration at a glance

A reliable migration typically includes inventory, SGML validation, parser-based conversion, XML validation, quality assurance and only then optional semantic redesign.

In this guide

• Why SGML data can still be valuable
• SGML-to-XML conversion with SX/OpenSP
• Converting the DTD
• A reproducible runnable example
• Quality assurance and common migration risks
• Migration architecture for large repositories

Why SGML Data Can Still Be Valuable

SGML is a legacy technology, but legacy technology does not automatically mean poor data.

A mature SGML collection can contain explicit chapters, metadata, identifiers, figures, tables, cross-references and domain semantics. The problem is often the surrounding environment: editor support has faded, publishing systems have been retired and specialist knowledge has become scarce.

The goal of migration is therefore often to preserve the structure while replacing the obsolete processing environment.

Why SGML is not simply old XML

Real SGML applications may use omitted tags, unquoted attributes, minimization, inclusions, exclusions and entity mechanisms that XML restricts or does not support.

That is why an SGML file cannot safely be converted by changing its extension or running generic search-and-replace rules. The source must first be parsed according to its SGML grammar.

A simple example

With an appropriate SGML declaration and DTD, omitted end tags and an unquoted attribute value can be legal. The equivalent XML must make these structures explicit.

From SGML to XML with SX and OpenSP

James Clark's SP software became one of the best-known SGML parser implementations. SX was designed to convert SGML to XML, and OpenSP continues that role with the osx command.

OpenSP documents osx as an SGML-to-XML converter that parses and validates the SGML source, writes equivalent XML to standard output and warns about SGML constructs with no XML equivalent.

Why a parser matters

A parser can use the DTD to reconstruct omitted tags, interpret declarations and resolve entities. This turns implicit SGML structure into explicit XML structure.

Basic command

The -c option supplies a catalog for identifier and entity resolution. OpenSP documents UTF-8 as the default output encoding.

The downloadable example must use the exact command that has been executed and verified against the installed OpenSP version.

Do not replace parsing with regular expressions

Search-and-replace can change characters. It cannot reliably reconstruct structure that depends on SGML declarations, content models, tag omission rules or entity resolution.

Converting the SGML DTD for XML

The document instances are only half of the migration. The target XML also needs a grammar.

SGML minimization parameters are not part of XML DTD syntax. Inclusions and exclusions have no direct XML DTD equivalent. Entity declarations and other SGML constructs may also require redesign.

Example: minimization parameters

An XML DTD does not use those minimization indicators:

Separate structural grammar from contextual rules

This can be clearer and more maintainable than reproducing every historical SGML rule literally.

Entities and encodings

Create an entity inventory and explicitly decide whether each entity is expanded, preserved, converted to Unicode, represented as a resource reference or handled by another inclusion mechanism.

Legacy character encodings should be tested deliberately. UTF-8 output does not by itself prove that every source character was interpreted correctly.

A Reproducible SGML-to-XML Migration Example

The example accompanying this article contains source SGML that is valid SGML but not already well-formed XML, together with its DTD, catalog, entities, conversion scripts, validation scripts and expected XML output.

Package structure

What is tested

• SGML parsing and validation
• catalog and entity resolution
• SGML-to-XML conversion with OpenSP osx
• XML well-formedness
• target grammar validation where applicable
• comparison with the expected result
• error handling and exit codes

Run the example

On Windows, use run.cmd or .\run.ps1.

The conversion script validates the SGML source with onsgmls -c catalog -s sgml/manual.sgm and then runs osx -c catalog sgml/manual.sgm > xml/manual.xml. The validation script checks XML well-formedness, validates the generated XML against dtd/manual-xml.dtd and compares the result with xml/expected.xml after XML canonicalization.

Download the complete example

sgml-to-xml-example.zip

Quality Assurance for SGML-to-XML Migration

Validation is necessary, but it is not sufficient.

A document can be valid XML while containing incorrect references, missing figures or changed semantics. A professional migration therefore combines parser validation with repository-level quality checks.

Recommended checks

• source and target document counts
• chapter, figure and table counts
• unique IDs
• resolvable references
• present external resources
• character encoding test cases
• application-specific Schematron rules

Typical risks

• missing DTD modules or entity files
• obsolete public identifiers or catalogs
• invalid source SGML
• character encoding mismatches
• SGML inclusions or exclusions that require a new validation strategy
• proprietary processing instructions or application conventions

Classify these issues instead of silently repairing them.

Migrating Large SGML Collections at Scale

Large repositories should be processed as repeatable pipelines with explicit logs and measurable quality gates.

Separate technical conversion from semantic redesign

First create structurally equivalent XML. Then use XSLT or another controlled transformation to map the intermediate XML into the new target vocabulary.

This makes it easier to identify whether an error was introduced during SGML parsing or during later semantic transformation.

What becomes possible after migration

• XSLT-based publishing
• XPath and XQuery
• XSD, RELAX NG and Schematron validation
• HTML, PDF and EPUB output
• search, APIs and content repositories
• structured input for RAG and AI workflows

Conclusion

SGML is old. Structured content is not. Preserve the DTDs, catalogs and entities, parse the source as SGML, validate the result and only then continue with XML modernization.