Migration

Migrating from SGML sources

SGML content — MIL-STD-40051-B era manuals, older logistics data, legacy commodity TMs — carries structural intent that can often be preserved through conversion to XML, and some that cannot. That is what the disposition report is for. Ironmark converts the content on ingest and lands the result in a standard project, so downstream authoring, review, and publishing behave the same as they do for native-authored content.

What auto-conversion handles

Structural

SGML → conformant XML — declaration, DOCTYPE, entity references
Tag-case normalization (SGML permissive → XML strict)
Attribute quoting + minimization expansion
Empty-element normalization
Namespace injection where the target schema requires it

Content

40051-B → 40051-C element-name remapping via the tag map. This is a name-for-name substitution, not a semantic B-to-C migration. Anything requiring interpretation is reported, not guessed.
Character-entity resolution against the source DTD
Graphics reference rewriting to project-local ICNs
Source attributes with no equivalent in the target model are carried under a data-legacy- prefix rather than dropped, and each one is itemised in the conversion report. This is the only Ironmark-specific markup added during conversion, and it exists solely so source information is not lost silently.
Where the source cannot supply a value the target model requires, the converter fills a documented default and records it as an assumption to resolve — it is never left looking like a determination.
DTD folder retained if the source manual has a customer variant

What "fidelity" means here

“Lossless” is a weaker promise than it sounds — a converter that retains every byte of editor state while quietly losing one odd legacy element is not the safer one. Ironmark commits to a disposition for each case instead, and each has a corresponding entry in the conversion report:

Unknown structure → preserve it.
Unmappable attribute → carry it explicitly.
Missing required target value → default it, but mark the assumption.
Known vendor artifact → discard it, and report it.
Semantic ambiguity → report it; don't guess.

What needs a hand

Auto-conversion is a starting line, not a finish line. Two categories consistently need human review:

Semantically ambiguous constructs — SGML tolerates shapes that XML doesn't, and the tolerated shape can encode meaning that isn't obvious from tags alone (e.g. inferred paragraph breaks, implied structure from indent). The converter flags these; a human decides.
Legacy-specific element usage — programs that extended their SGML DTD with local elements need a tag-map entry for each local element. Unmapped elements get a passthrough so the content is preserved, but they won't validate against the target schema until mapped.

Path through the tool

1. Create a project on the target SDM

Pick the SDM the converted content should land in (40051-C, S1000D 4.2 / 5.0 / 6.0, 63029). This becomes the validation target.

2. Ingest the SGML source

Upload as a source archive. Ironmark converts each source file, records disposition (converted / passed-through / rejected), and produces a report of unmapped elements and structural warnings.

3. Review the conversion report

The report lists every non-clean disposition with the source line reference. Unmapped elements aggregate to show which local extensions need tag-map entries. Structural warnings link to the source location.

4. Fix + re-ingest, or commit

For unmapped elements, extend the project's tag map and re-run ingest against the same source archive — Ironmark idempotently overwrites the prior conversion. For content-level fixes, commit and edit in the structured editor.

5. Baseline the pre-edit state

Before beginning content edits, cut a baseline. That gives you a rollback anchor if the auto-conversion result turns out to need re-work, and a provenance point for auditors who want to see "the manual as it came in from the legacy source."

Auto-conversion should never silently drop content with publication meaning — but “lossless” is not the same as keeping every byte. Ironmark separates the two cases. Unrecognized elements pass through with their source tags, so their content survives even if the result cannot yet validate. Recognized authoring-tool artifacts — an editor’s <?Pub …?> instruction, a vendor banner comment — are deliberately discarded, because carrying decades of editor detritus into normalized XML is not preservation. Both dispositions are counted in the conversion report, so the review pass is concerned with “what needs remapping” rather than “what got lost,” and nothing is removed without an entry accounting for it.

← All migration guides