Konvertieren von Ami Pro .SAM zu Markdown für Docs-Pipelines

Warum Markdown für ältere Dokumente

Docs-as-Code hat die Bedeutung von „Dokumentation haben“ verändert. Inhalte in einem Repository erhalten Versionsverlauf, Code-Review, automatisierte Link-Prüfung und eine Build-Pipeline. Inhalte in einem proprietären Binärformat erhalten nichts davon – und eine .sam-Datei bekommt weniger als nichts, weil kein Werkzeug in der Kette sie überhaupt lesen kann.

Die Umwandlung in Markdown verschiebt Jahrzehnte an Material in denselben Arbeitsablauf wie alles andere. Ein Installationsverfahren von 1995 wird zu einer Datei, die Sie mit ihrer Revision von 2002 vergleichen, in einer Pull-Anfrage kommentieren und über denselben statischen Site-Generator veröffentlichen können wie die Veröffentlichungsnotizen dieses Quartals.

Markdown ist auch die langlebigste praktische Wahl, die verfügbar ist. Es ist Klartext mit einer leichten Konventionsebene: lesbar ohne jegliche Software, von Dutzenden von Implementierungen parsend, und wandelbar in HTML, PDF, DOCX oder alles andere auf Nachfrage. Da das ganze Problem damit begann, dass ein Vendor-Format seinen Anbieter überlebte, ist diese Portabilität der Sinn der Sache.

Was sich sauber abbildet und was nicht

Markdown ist bewusst minimalistisch, was seine Stärke und seine Grenze ist. Struktur lässt sich gut übersetzen; Präsentation nicht, und das ist normalerweise in Ordnung, weil Präsentation ohnehin die Schicht ist, die man ersetzen möchte.

• Überschriften — Ami Pro-Stile aus dem .STY-Blatt werden zu Markdown-Überschriftsebenen und verleihen der Dokumentstruktur echte Gliederung
• Listen – Aufzählungs- und nummerierte Listen werden in Standard-Markdown-Listen umgewandelt, einschließlich Verschachtelung
• Betonung — fett und kursiv werden direkt abgebildet; unterstrichen hat kein Markdown-Äquivalent und wird typischerweise zu Betonung
• Tabellen — einfache Tabellen werden zu Pipetabellen; komplexe Layouts mit zusammengeführten Zellen können nicht dargestellt werden und benötigen HTML-Fallback oder eine Notiz
• Bilder — extrahierte WMF/EMF-Diagramme werden als Dateien geschrieben und mit dem Standard-Bildsyntax referenziert
• Gleichungen — verfügbar als LaTeX für math-fähige Renderer oder als verlinkte Bilder, wo sie nicht unterstützt werden

Stylesheets sind das, was Überschriften möglich macht

Dies ist das Detail, das entscheidet, ob die Markdown-Konvertierung nützlich oder wertlos ist. Markdown hat kein Konzept von „16-Punkt fette Helvetica“ — es hat Überschriftenebenen. Die einzige Möglichkeit, wie ein Konverter erkennen kann, dass eine Zeile eine Überschrift der Stufe zwei und kein hervorgehobener Absatz ist, besteht darin, den Absatzstil anhand des .STY-Stilblatts aufzulösen.

Mit dem vorhandenen Stylesheet kommt ein konvertiertes Dokument mit einer Überschriftenhierarchie an, aus der Sie ein Inhaltsverzeichnis erstellen und in Abschnitte unterteilen können. Ohne es erhalten Sie eine flache Abfolge von Absätzen mit gelegentlich fettgedruckten Zeilen, und jeder der oben genannten Vorteile entfällt.

Überprüfen Sie also vor der Konvertierung eines Archivs für eine Dokumentations-Pipeline, ob die .STY-Dateien vom alten Server übertragen wurden. Es dauert eine Minute und bestimmt das Ergebnis des gesamten Projekts.

Verarbeitung von Bildern in einem Repository

Überprüfung von Tausenden konvertierter Dateien

Niemand liest dreitausend Markdown Dateien, aber Git macht eine selektive Überprüfung in einer Weise möglich, die ein Ordner mit DOCX Dateien nicht bietet. Bringen Sie die Konvertierungsausgabe als einen einzigen großen Commit auf einem Branch unter und überprüfen Sie dann nach Mustern statt nach Dateien.

Grep ist hier das Hauptwerkzeug. Suchen Sie nach verdächtig kurzen Dateien, Dateien ohne jegliche Überschrift, ungelösten Bildreferenzen, herumliegenden geklammerten Markups, die auf eine Parsing-Lücke hinweisen, und Ersatzzeichen, die auf ein Kodierungsproblem hindeuten. Jede dieser Suchen deckt in Sekunden eine Fehlerklasse auf.

Fügen Sie währenddessen Automatisierung zur Pipeline hinzu: einen Link-Checker, um defekte interne Verweise zu erfassen, einen Front-Matter-Validator, wenn Ihr Generator diesen benötigt, und einen Build-Schritt, der bei fehlenden Bildern fehlschlägt. Sobald diese bestehen, ist das Archiv in derselben Qualitätsstufe wie Ihre gepflegte Dokumentation.

Wo Markdown das falsche Ziel ist

Markdown kann bewusst keine komplexen Seitenlayouts ausdrücken, und einige Ami Pro-Dokumente wurden eher gestaltet als geschrieben – Newsletter, formatierte Formulare, Berichtsumschläge mit rahmenbasierter Komposition. Diese in Markdown zu zwängen erzeugt etwas technisch Gültiges und praktisch Nutzloses.

Das Gleiche gilt für Dokumente, deren Bedeutung rechtlich ist und von einer genauen Darstellung abhängt: ausgeführte Verträge, unterzeichnete Formulare, amtliche Mitteilungen. Für diese ist PDF die ehrliche Ausgabe, und wenn Sie möchten, dass sie zusammen mit Markdown auffindbar sind, konvertieren Sie in beide und verlinken Sie das PDF von einem kurzen Markdown-Stub aus.

Selektiv zu sein ist kein Kompromiss. Ein Dokumentenarchiv voller sauberer, strukturierter Markdown plus einem verknüpften Satz von PDFs für Dokumente, die ein festes Layout benötigen, ist ein besseres Ergebnis als ein einheitlicher Haufen verschlechterter Konvertierungen.