Muunnetaan Ami Pro .SAM muotoon Markdown Docs-pipelineja varten

TL;DR

Valitse Markdown, kun sisältö on menossa arkistoon, staattisen sivuston generaattoriin tai tekstiputkeen. Markdown on pieni, erovalmis ja siirrettävä: otsikot, listat, taulukot ja linkit säilyvät, erotetut kaaviot muuttuvat linkitetyiksi kuviksi, ja yhtälöiden LaTeX säilyy. Yhdistettynä Gitiin muunnettu Ami Pro-arkisto voidaan tarkastella pull requesteissa sen sijaan, että siihen luotettaisiin sokeasti. Muunna Ami Pro Converter:lla.

Miksi Markdown vanhoille asiakirjoille

Docs-as-code muutti sen, mitä "dokumentaation omistaminen" tarkoittaa. Sisältö repositoriossa saa version historian, koodikatselmoinnin, automaattisen linkkien tarkistuksen ja rakennusputken. Sisältö omaa binäärimuotoa käyttävässä muodossa ei saa mitään näistä — ja .sam-tiedosto saa vähemmän kuin ei mitään, koska yksikään ketjun työkaluista ei voi edes lukea sitä.

Muuntaminen Markdown:ksi siirtää vuosikymmenten materiaalin samaan työnkulkuun kaiken muun kanssa. Vuoden 1995 asennusohjeesta tulee tiedosto, jota voit verrata sen vuoden 2002 versioon, tehdä siihen merkintöjä pull requestissa ja julkaista sen saman staattisen sivustogeneraattorin kautta kuin tämän neljänneksen julkaisumuistiot.

Markdown on myös käytännöllisesti kestävin saatavilla oleva vaihtoehto. Se on tavallista tekstiä, jossa on kevyt konventiokerros: luettavissa ilman mitään ohjelmistoa, jäsenneltävissä kymmenien toteutusten avulla ja muunnettavissa HTML-PDF-DOCX- tai mihin tahansa muuhun tarpeen mukaan. Kun koko ongelma alkoi toimittajalta peräisin olevan formaatin elämää pidemmällä elinkaarella, juuri tämä siirrettävyys on olennaista.

Mikä karttuu puhtaasti, ja mikä ei

Markdown on tarkoituksellisesti minimaalinen, mikä on sen vahvuus ja sen raja. Rakenne kääntyy hyvin; esitys ei, ja se on yleensä hyvä, koska esitys on kerros, jonka haluat joka tapauksessa korvata.

Otsikot — Ami Pro-tyylit .STY-taulukosta muuttuvat Markdown-otsikkotasoiksi, mikä antaa todellisen asiakirjarakenteen
Luettelot — luetellut ja numeroidut listat muunnetaan standardeiksi Markdown-listoiksi, mukaan lukien sisäkkäisyys
Painotus — lihavoitu ja kursivoitu vastaavat suoraan; alleviivausta ei ole Markdown-vastinetta ja se muuttuu tyypillisesti painotukseksi
Taulukot — yksinkertaiset taulukot muuttuvat putkitaulukoiksi; monimutkaisia yhdistettyjen solujen asetteluja ei voida esittää ja ne tarvitsevat HTML-vararatkaisun tai huomautuksen
Kuvat — erotetut WMF/EMF-kaaviot tallennetaan tiedostoina ja viitataan niihin vakiokuvasyntaksilla
Yhtälöt — saatavilla LaTeX-muodossa matemaattisesti kykeneville renderöijille, tai linkitettyinä kuvia, missä niitä ei ole

Tyyliarkit ovat se, mikä tekee otsikoista mahdollisia

Tämä on yksityiskohta, joka ratkaisee, onko Markdown-muunnos hyödyllinen vai arvoton. Markdown:llä ei ole käsitystä "16 pisteen lihavoitu Helvetica" -fontista — sillä on otsikkotasot. Ainoa tapa, jolla muunnin voi tietää, että rivi on tason kaksi otsikko eikä korostettu kappale, on ratkaista kappaleen tyyli .STY-tyyliohjeen avulla.

Tyylisivun ollessa käytettävissä muunnettu asiakirja saapuu otsikkorakenteella, josta voit laatia sisällysluettelon ja jakaa osiin. Ilman sitä saat tasaisen jonoa kappaleita satunnaisilla lihavoiduilla riveillä, ja kaikki edellä mainitut hyödyt haihtuvat.

Joten ennen arkiston muuntamista dokumenttiputkelle, varmista, että .STY-tiedostot siirtyivät vanhalta palvelimelta. Se vie minuutin ja se määrittää koko projektin lopputuloksen.

Kuvien käsittely arkistossa

1. Päätä, missä varat sijaitsevat

Useimmat staattiset sivustogeneraattorit odottavat kuvia omassa hakemistossaan tai sivun kanssa samassa paikassa. Valitse käytäntö ennen muuntamista, jotta siirrät tiedostoja vain kerran etkä joudu uudelleennimeämään viittauksia tuhansissa Markdown tiedostoissa jälkeenpäin.

2. Tarkkaile varaston kokoa

Erotetut kaaviot kertautuvat. Muutamat tuhannet kuvia sisältävät asiakirjat voivat lisätä satoja megatavuja aiemmin pelkästään tekstiä sisältävään varastoon. Harkitse Git LFS:ää tai pidä aineistot objektivarastossa ja viittaa niihin URL-osoitteella.

3. Normalisoi tiedostonimet

Perintöarkistot ovat täynnä DOS-ajan nimiä, välilyöntejä ja sekoitettua kirjasinkokoa. Normalisoi nimet pieniksi kirjaimiksi yhdysviivoin siirron aikana ja pidä vastaustaulukko, jotta voit edelleen jäljittää julkaistun sivun alkuperäiseen .sam-tiedostoon.

4. Valitse yhtälöstrategia aluksi

Jos sivustosi näyttää matemaattisia kaavoja, käytä poimittua LaTeXia ja saa teräviä, valittavia, haettavia kaavoja. Jos se ei näytä, käytä renderöityjä kuvia ja hyväksy, että matematiikka ei ole haettavissa. Molempien sekoittaminen samassa arkistossa on vaihtoehto, jota tulisi välttää.

Tuhansien muunnettujen tiedostojen tarkastelu

Kukaan ei lue kolmea tuhatta Markdown tiedostoa, mutta Git tekee valikoivan tarkastelun hallittavaksi tavalla, johon DOCX tiedostoja sisältävä kansio ei pysty. Vie muunnoksen tulos yhtenä suurena committina haaraan, ja tarkastele sitten kuvion mukaan tiedostojen sijaan.

Grep on tässä pääasiallinen työkalu. Etsi epäilyttävän lyhyitä tiedostoja, tiedostoja, joilla ei ole lainkaan otsikkoa, ratkaisemattomia kuvaviittauksia, harhaisia sulkumerkein merkittyjä merkintöjä, jotka viittaavat jäsennysaukkoon, ja korvausmerkkejä, jotka viittaavat koodausongelmaan. Jokainen näistä hauista tuo esiin tietyn luokan virheitä sekunneissa.

Lisää automaatio putkistoon samalla: linkintarkistaja rikkoontuneiden sisäisten viitteiden havaitsemiseksi, etuosa-tarkistin, jos generaattorisi sitä vaatii, ja rakennusvaihe, joka epäonnistuu puuttuvien kuvien kohdalla. Kun nämä läpäisevät, arkisto on samassa laatuluokassa kuin ylläpitämäsi dokumentaatio.

Missä Markdown on väärä kohde

Markdown ei tarkoituksellisesti pysty ilmaisemaan monimutkaista sivun asettelua, ja jotkut Ami Pro-asiakirjat suunniteltiin kirjoittamisen sijaan — uutiskirjeet, muotoillut lomakkeet, kehyspohjaisen rakenteen raporttikannet. Niiden pakottaminen Markdown-muotoon tuottaa jotain teknisesti pätevää mutta käytännössä hyödytöntä.

Sama koskee asiakirjoja, joiden merkitys on oikeudellinen ja riippuu tarkasta esitystavasta: allekirjoitetut sopimukset, täytetyt lomakkeet, viralliset ilmoitukset. Niiden osalta PDF on rehellinen tulos, ja jos haluat niiden olevan löydettävissä yhdessä Markdown kanssa, muunna molemmat ja linkitä PDF lyhyestä Markdown-pätkästä.

Olla valikoiva ei ole kompromissi. Dokumenttivarasto, joka on täynnä puhdasta, jäsenneltyä Markdown:ää plus linkitetty joukko PDF:ja asiakirjoille, jotka tarvitsevat kiinteän asettelun, on parempi tulos kuin tasainen kasa heikentyneitä muunnoksia.

Mitä Markdown antaa vanhalle arkistolle

Versiohistoria, katselmointi ja vertailut asiakirjoille, joilla niitä ei ole koskaan ollut
Julkaistavissa samalla staattisten sivustojen generaattorilla kuin nykyinen dokumentaatio
Pieniä, siirrettäviä pelkkää tekstiä olevia tiedostoja, jotka kestävät pidempään kuin mikään yksittäinen työkalu
Otsikkorakenne, joka sopii sisällysluetteloihin ja tekoälyn pilkkomiseen
LaTeX-kaavat pysyvät haettavina eivätkä muutu kuviksi

Perintödokumentit ansaitsevat nykyaikaiset työkalut

Aukko .sam-tiedoston ja Markdown-tiedoston välillä repositoriossa ei ole pelkkä formaatimuutos. Se on ero sisällön välillä, jota kukaan ei voi tarkastella, ja sisällön välillä, joka osallistuu tarkasteluun, hakuun ja automatisoituun julkaisuun kuten kaikki muu, mitä tiimisi kirjoittaa.

Vahvista tyylitiedostot, päätä resurssi- ja yhtälökonventiosi ennen aloittamista, muunna arkisto yhdellä kertaa ja tarkista se grep-ohjelmalla lukemisen sijaan. Lähetä sitten se saman putken läpi kuin muun dokumentaation.