Converteer Ami Pro .SAM naar Markdown voor Docs-pijplijnen

Waarom Markdown voor legacydocumenten

Docs-as-code heeft veranderd wat "documentatie hebben" betekent. Inhoud in een repository krijgt versiegeschiedenis, codebeoordeling, geautomatiseerde linkcontrole en een build-pijplijn. Inhoud in een propriëtair binair formaat krijgt niets van dat alles — en een .sam-bestand krijgt minder dan niets, omdat geen enkel hulpmiddel in de keten het zelfs maar kan lezen.

Het converteren naar Markdown verplaatst decennia aan materiaal in dezelfde workflow als alles anders. Een installatieprocedure uit 1995 wordt een bestand waarop je een verschil kunt zien ten opzichte van de herziening uit 2002, annotaties kunt toevoegen in een pull request en kunt publiceren via dezelfde statische sitegenerator als de release-opmerkingen van dit kwartaal.

Markdown is ook de meest duurzame praktische keuze die beschikbaar is. Het is platte tekst met een lichte conventielaag: leesbaar zonder enige software, parseerbaar door tientallen implementaties, en converteerbaar naar HTML, PDF, DOCX of iets anders op aanvraag. Aangezien het hele probleem begon met een leveranciersformaat dat zijn leverancier overleefde, is die draagbaarheid het punt.

Wat netjes in kaart wordt gebracht, en wat niet

Markdown is opzettelijk minimaal, wat zowel zijn kracht als zijn beperking is. Structuur vertaalt goed; presentatie niet, en dat is meestal prima omdat presentatie de laag is die je toch wilt vervangen.

• Koppen — Ami Pro stijlen uit het .STY-blad worden Markdown kopniveaus, wat zorgt voor echte documentstructuur
• Lijsten — opsommingstekens en genummerde lijsten worden omgezet naar standaard Markdown-lijsten, inclusief geneste lijsten
• Accent — vet en cursief worden direct vertaald; onderstrepen heeft geen Markdown-equivalent en wordt meestal nadruk
• Tabellen — eenvoudige tabellen worden pijptabellen; complexe lay-outs met samengevoegde cellen kunnen niet worden weergegeven en hebben een HTML-terugval of een notitie nodig
• Afbeeldingen — geëxtraheerde WMF/EMF-diagrammen worden als bestanden geschreven en verwezen met standaard afbeeldingssyntaxis
• Vergelijkingen — beschikbaar als LaTeX voor wiskundig-capabele weergaves, of als gekoppelde afbeeldingen waar dit niet mogelijk is

Stijlbladen zijn wat koppen mogelijk maakt

Dit is het detail dat bepaalt of Markdown conversie nuttig of waardeloos is. Markdown heeft geen concept van "16-punts vetgedrukte Helvetica" — het heeft kopniveaus. De enige manier waarop een converter kan weten dat een regel een kop van niveau twee is in plaats van een benadrukt alinea, is door de alinea-stijl te vergelijken met het .STY-stijlsheet.

Met het stijlsheet aanwezig, arriveert een geconverteerd document met een kophiërarchie waarvan je een inhoudsopgave kunt maken en waarmee je kunt segmenteren. Zonder het krijg je een vlakke reeks alinea's met af en toe een vetgedrukte regel, en verdwijnt elk van de bovenstaande voordelen.

Dus voordat je een archief converteert voor een documentenpipeline, controleer of de .STY-bestanden van de oude server zijn overgekomen. Het kost een minuut en het bepaalt het resultaat van het hele project.

Afbeeldingen beheren in een repository

Het herzien van duizenden geconverteerde bestanden

Niemand leest drieduizend Markdown bestanden, maar Git maakt selectieve beoordeling haalbaar op een manier die een map met DOCX bestanden niet doet. Plaats de conversie-output als een enkele grote commit op een tak, en beoordeel vervolgens op patroon in plaats van op bestand.

Grep is hier het belangrijkste hulpmiddel. Zoek naar verdacht korte bestanden, bestanden zonder koptekst, onopgeloste afbeeldingverwijzingen, losstaande tussen haakjes geplaatste opmaak die een parseerfout aangeeft, en vervangingskarakters die een coderingsprobleem aangeven. Elk van die zoekopdrachten brengt binnen enkele seconden een klasse van fouten aan het licht.

Voeg automatisering toe aan de pipeline terwijl je bezig bent: een linkchecker om gebroken interne verwijzingen te detecteren, een front-matter validator als je generator dat vereist, en een build-stap die faalt bij ontbrekende afbeeldingen. Zodra die doorgaan, bevindt het archief zich in hetzelfde kwaliteitsregime als je onderhouden documentatie.

Waar Markdown het verkeerde doel is

Markdown kan opzettelijk geen complexe paginalay-out uitdrukken, en sommige Ami Pro documenten waren ontworpen in plaats van geschreven — nieuwsbrieven, opgemaakte formulieren, rapportomslagen met frame-gebaseerde samenstelling. Die erin dwingen naar Markdown produceert iets technisch geldig en praktisch nutteloos.

Hetzelfde geldt voor documenten waarvan de betekenis juridisch is en afhankelijk is van exacte presentatie: getekende contracten, ondertekende formulieren, officiële kennisgevingen. Voor deze documenten is PDF de eerlijke weergave, en als je ze samen met de Markdown vindbaar wilt maken, converteer dan naar beide en link de PDF vanaf een korte Markdown-stub.

Selectief zijn is geen compromis. Een documentatie-repository vol met schone, gestructureerde Markdown plus een gekoppelde set van PDF's voor documenten die een vaste opmaak nodig hebben, is een beter resultaat dan een uniforme stapel van verslechterde conversies.