Conversione di Ami Pro .SAM in Markdown per Docs Pipelines

Perché Markdown per i documenti legacy

Docs-as-code ha cambiato il significato di "avere documentazione". Il contenuto in un repository ottiene la cronologia delle versioni, la revisione del codice, il controllo automatico dei link e una pipeline di build. Il contenuto in un formato binario proprietario non ottiene nulla di tutto ciò — e un file .sam ottiene meno di nulla, perché nessun tool nella catena può nemmeno leggerlo.

Convertire in Markdown sposta decenni di materiale nello stesso flusso di lavoro di tutto il resto. Una procedura di installazione del 1995 diventa un file che puoi confrontare con la sua revisione del 2002, annotare in una pull request e pubblicare attraverso lo stesso generatore di siti statici delle note di rilascio di questo trimestre.

Markdown è anche la scelta pratica più duratura disponibile. È testo semplice con uno strato leggero di convenzioni: leggibile senza alcun software, analizzabile da decine di implementazioni e convertibile in HTML, PDF, DOCX o qualsiasi altra cosa su richiesta. Dato che l'intero problema è iniziato con un formato del fornitore che ha superato la vita del suo fornitore, quella portabilità è il punto centrale.

Cosa si mappa facilmente e cosa no

Markdown è deliberatamente minimale, il che è la sua forza e il suo limite. La struttura si traduce bene; la presentazione no, e di solito va bene così perché la presentazione è comunque lo strato che vuoi sostituire.

• Intestazioni — gli stili Ami Pro dal foglio .STY diventano livelli di intestazione Markdown, fornendo una vera struttura del documento
• Elenchi — gli elenchi puntati e numerati vengono convertiti in elenchi standard Markdown, inclusi quelli nidificati
• Enfasi — grassetto e corsivo si traducono direttamente; il sottolineato non ha un equivalente Markdown e di solito diventa enfasi
• Tabelle — le tabelle semplici diventano tabelle a pipe; i layout complessi con celle unite non possono essere rappresentati e necessitano di un fallback HTML o di una nota
• Immagini — i diagrammi WMF/EMF estratti vengono scritti come file e riferiti tramite la sintassi standard delle immagini
• Equazioni — disponibili come LaTeX per chi può visualizzare formule matematiche, oppure come immagini collegate dove non è possibile

I fogli di stile sono ciò che rende possibili i titoli

Questo è il dettaglio che decide se la conversione Markdown sia utile o inutile. Markdown non ha il concetto di "Helvetica grassetto 16 punti" — ha livelli di intestazione. L'unico modo in cui un convertitore può sapere che una riga è un'intestazione di livello due piuttosto che un paragrafo enfatizzato è risolvendo lo stile del paragrafo rispetto al foglio di stile .STY.

Con il foglio di stile presente, un documento convertito arriva con una gerarchia di titoli dalla quale è possibile creare un sommario e suddividerlo in sezioni. Senza di esso, si ottiene una sequenza piatta di paragrafi con occasionali righe in grassetto, e ciascuno dei vantaggi sopra menzionati svanisce.

Quindi, prima di convertire un archivio per un flusso di lavoro di documenti, verifica che i file .STY siano stati trasferiti dal vecchio server. Ci vuole un minuto e determina l'esito dell'intero progetto.

Gestione delle immagini in un repository

Revisionare migliaia di file convertiti

Nessuno legge tremila file Markdown, ma Git rende la revisione selettiva praticabile in un modo che una cartella di file DOCX non fa. Inserisci l'output della conversione come un unico grande commit su un branch, quindi rivedi per modello piuttosto che per file.

Grep è lo strumento principale qui. Cerca file sospettosamente brevi, file senza alcun titolo, riferimenti a immagini non risolti, markup tra parentesi sparsi che indicano un'interruzione di parsing e caratteri di sostituzione che indicano un problema di codifica. Ognuna di queste ricerche fa emergere una classe di errori in pochi secondi.

Aggiungi automazione al flusso di lavoro mentre ci sei: un controllo dei link per rilevare riferimenti interni non funzionanti, un validatore del front-matter se il tuo generatore lo richiede e un passaggio di build che fallisce se mancano immagini. Una volta superati questi controlli, l'archivio è nello stesso regime di qualità della tua documentazione mantenuta.

Dove Markdown è il bersaglio sbagliato

Markdown non può esprimere deliberatamente layout di pagina complessi, e alcuni documenti Ami Pro sono stati progettati piuttosto che scritti — newsletter, moduli formattati, copertine di report con composizione basata su cornici. Costringere questi documenti in Markdown produce qualcosa di tecnicamente valido e praticamente inutile.

Lo stesso vale per i documenti il cui significato è legale e dipende dalla presentazione esatta: contratti eseguiti, moduli firmati, avvisi ufficiali. Per questi, PDF è il risultato onesto, e se vuoi renderli rintracciabili insieme al Markdown, converti in entrambi e collega il PDF da un breve stub Markdown.

Essere selettivi non è un compromesso. Un repository di documenti pieno di Markdown puliti e strutturati più un insieme collegato di PDF per documenti che necessitano di un layout fisso è un risultato migliore rispetto a un mucchio uniforme di conversioni degradate.