Kuinka luoda GitHub-merkintätiedosto Microsoft Wordista TypeScriptillä

Mitä? Miksi MD-tiedosto halutaan luoda Microsoft Word -asiakirjasta? Jos tämä on ensimmäinen ajatuksesi luettuasi tämän otsikon, anna minun antaa sinulle vahva käyttötapaus.

Harkitse tilannetta, jossa käytät Git-ohjelmistoa tai muuta versionhallintajärjestelmää (VCS) projektisi lähteille ja sen artefakteille. Nyt, kuten useimmat projektit, päätät käyttää Microsoft-sanaa dokumentointiin ja tarkistaa sen Gitiin. Jälleen kerran useat tiimin jäsenet muokkaavat samaa asiakirjaa. Muokkaamisen jälkeen he kirjaavat asiakirjan arkistoon.

Nyt Git pystyy ylläpitämään dokumenttisi historiaa. Kuinka pystyt tarkastelemaan muutoksia, jotka on tehty asiakirjaan sen jälkeen, kun viimeksi kirjait sen sisään? Kyllä, voit käyttää Microsoft-sanan raidanvaihtotilaa, mutta eikö se ole sotkuista? Tai taivaan tähden, pystytkö Git diff -apuohjelman avulla tarkistamaan erot nopeasti? Sanoisin, ei.

Mikä sitten on ratkaisu? Pitäisikö sinun lopettaa Microsoft Wordin käyttö dokumentaatioon? Vai pitäisikö sinun vaihtaa johonkin muuhun VCS: ään?

En sanoisi kumpikaan. Entä jos säilytät dokumentaation Microsoft Word -palvelussa? Vaihda sitten se markdown (MD) -tiedostoksi (maallikkona, tekstitiedostoksi) rakennusvaiheen aikana ja kirjaudutko sisään? Jos ratkaisu innostaa sinua, jatka lukemista.

Mutta ennen kuin siirryt muunnokseen, anna minun ensin kertoa mikä tarkalleen on markdown-tiedosto.

Mikä on markdown tai MD-tiedosto?

Markdown on syntaksikieli, jonka tarkoituksena on helpottaa rakenteellisen tekstin lukemista ja kirjoittamista. Lisäksi se on helppo oppia, ja asiakirjan luominen vaatii vain tekstieditorin.

Kielellä on nyt useita toteutuksia (kuten GFM eli Github-maustettu Markdown). Jokaisella näistä toteutuksista on omat parannuksensa ja ominaisuudet, jotka eivät välttämättä ole yhteensopivia keskenään.

Jokainen toteutus tukee useita yleisiä ominaisuuksia, kuten kappaleita, lauseita, otsikoita ja luetteloita. Tämä auttaa ylläpitämään tekstiä jäsennellyllä tavalla, kuten Microsoft Word. Mutta sisäisten binaarikoodien käyttämisen sijaan MD-tiedostot käyttävät näihin ominaisuuksiin pelkkää tekstiä. Tämä tekee MD-tiedostosta tekstitiedoston, mutta ei binääritiedostoa, kuten docx-tiedosto.

Esimerkiksi GitHubin merkintämakuissa tässä on useita ominaisuuksia ja tapoja esittää ne tekstimuodossa verrattuna Word-asiakirjaan.

Saat lisätietoja MD-tiedostojen eduista Word-asiakirjoihin verrattuna myös tähän artikkeliin.

OK! Olen vakuuttunut. Näytä koodi.

Vastuuvapauslauseke: Tämä projekti on saanut inspiraationsa TypeScript-lähdekoodista. Selaillessani löysin tämän ajatuksen muuntaa Word-asiakirja MD-tiedostoksi. Voit nähdä sen lähdekoodin täältä.

Yksinkertaisuuden vuoksi olen poistanut muutaman koodiosan arkistostani. Alkuperäisen koodin oli tarkoitus muuntaa TypeScript-määrittelydokumentaatio MD-tiedostoksi. Tämä tiedosto sisältää paljon mukautettuja tyylejä. Joten, kun olet valmis tämän artikkelin kanssa, voit käydä läpi TypeScript-muunninkoodin ja arvostaa sen kykyä suorittaa monimutkaisempia muunnoksia.

Tässä artikkelissa mainittuun täydelliseen koodiin voidaan viitata tässä. Koko koodi voidaan jakaa 3 osaan:

  1. Gulp-kokoonpanot.
  2. CScript-suoritus.
  3. TypeScript-päätoiminto

Kuten aiemmin todettiin, voit muuntaa Word-asiakirjan MD-tiedostoksi rakennusvaiheen aikana. Tämän voi tehdä kuka tahansa tehtävän juoksija. Täällä olen valinnut ruokailun.

Gulp-kokoonpanoissa olen määrittänyt 3 tehtävää. Ensinnäkin on puhdistettava rakennushakemisto, joka on melko vakio. Toinen on kääntää TypeScript-koodi. Viimeinen on kutsua CScript JavaScriptiä varten.

Mikä on CScript?

CScript.exe (esiintyy kielellä C: \ Windows \ System32) on konsolipohjainen suoritustiedosto komentosarjan isännälle, jota käytetään komentosarjojen suorittamiseen. Se voi tulkita komentosarjakieliä, kuten VB Script tai JavaScript. Vastaavasti meillä on WScript, mutta sitä käytetään Windows-sovelluksiin. Tässä konsoli ei ole kiinnitetty. Joten jos sinulla on vaatimus konsolipohjaisen sovelluksen luomisesta, voimme käyttää CScriptiä.

Nyt projektissamme CScriptin päätehtävä on tarjota ajoaikaympäristö skripillemme eli JavaScriptille. Nyt sinun on mietittävä, miksi en ole käyttänyt solmua CScriptin sijaan JavaScriptin suorittamiseen.

Molemmat tarjoavat ajoaikaympäristön JavaScriptille. CScript tarjoaa luontaisen tuen Windows-komponenttimallitekniikalle. Joten jos yrität suorittaa tämän komentosarjan solmun kautta, saat tällaisen virheen.

var fileStream = uusi ActiveXObject (“ADODB.Stream”); ReferenceError: ActiveXObjectia ei ole määritelty

Mikä on komponenttiobjektimallitekniikka?

Komponenttimallimalli on Microsoftin kehittämä tekniikka. Se ei ole kieli vaan binaarinen standardi. Määritelmän mukaisesti

Microsoft Component Object Model (COM) on alustasta riippumaton, hajautettu, olio-orientoitu järjestelmä vuorovaikutteisten binaaristen ohjelmistokomponenttien luomiseen. COM on Microsoftin OLE: n (yhdistelmäasiakirjat), ActiveX: n (Internet-yhteensopivat komponentit) ja muiden perustekniikka.

Maalliselta kannalta COM-objektit ovat rajapintoja erilaisiin ajonaikaisiin objekteihin. (Siksi määritelmässä on termi nimeltä "binaariset ohjelmistokomponentit"). Se ei ole kieli, vaan tekniikka, joka ohjelmoi kielen agnostiaa.

Ainoa COM-kielivaatimus on, että koodi luodaan kielellä, joka voi luoda osoitinrakenteita. Joko nimenomaisesti tai epäsuorasti, soita toiminnot osoittimien kautta. Objektikeskeiset kielet, kuten C ++ ja Smalltalk, tarjoavat ohjelmointimekanismeja, jotka yksinkertaistavat COM-objektien toteutusta

Sen jälkeen voimme käyttää mitä tahansa muuta kieltä, kuten Java, VB tai JavaScript vuorovaikutuksessa näiden COM-objektien kanssa. Tämä antaa meille edelleen pääsyn ajonaikaisiin sovelluksiin. Meidän tapauksessamme Microsoft-sanasovelluksiin.

Joten, sanotko, että emme voi käyttää solmua ollenkaan täällä?

Ei, se ei ole totta. Voimme käyttää solmua myös CScriptin sijaan. Mutta COM: n tukemiseksi meidän on asennettava toinen paketti nimeltä Win32com COM-tukea varten. Yksityiskohdat löydät täältä.

Lopullinen koodi

Nyt vuorovaikutuksessa sanasovelluksen kanssa on käytetty erilaisia ​​sovellusliittymiä. Ja koska käytämme COM-objektimallia, viittasin sanaobjektimalliin.

Word tarjoaa satoja esineitä, joiden kanssa voit olla vuorovaikutuksessa. Nämä objektit on järjestetty hierarkiaan, joka seuraa tarkasti käyttöliittymää. Hierarkian yläosassa on Application-objekti. Tämä objekti edustaa Wordin nykyistä esiintymää. Sovellusobjekti sisältää Document, Selection, Bookmark ja Range -objektit. Jokaisella näistä objekteista on monia menetelmiä ja ominaisuuksia, joita voit käyttää objektin manipulointiin ja vuorovaikutukseen sen kanssa.

Nyt skriptissämme olemme ensin luoneet sanasovelluksen objektin käyttämällä ActiveXObjectia. Kun sovellusobjekti on saatu, asiakirjaobjekti luodaan välittämällä asiakirjan nimi (saatu cscript-kutsun komentoriviargumenteista).

Nyt tämä edustaa varsinaisen asiakirjan aktiivista objektia. Tämä objekti pystyy jäsentämään sekä käsittelemään Word-asiakirjaa. Käyttötapauksessamme meidän on kuitenkin vain jäsennettävä asiakirja ja kirjoitettava tekstitiedosto.

Tämä koodi on hyvin yleinen, jota käytetään muuntaa sanadokumentin perusominaisuudet, kuten ristiviittaukset, luettelot, alaindeksitekstit, lihavoidut ja kursivoidut merkit jne. GFM-muotoon. Voit kuitenkin kirjoittaa oman koodisi muuntamalla sana-asiakirjan mukautetut tyylit haluttuun muotoon.

Todellisen konekirjoituskoodin löydät täältä. Koodi on melko helppo lukea. Alla on muutamia tärkeimpiä kohokohtia:

  1. Ensin siirretään asiakirjaobjekti convertDocumentToMarkdown-funktiolle, joka palauttaa MD-tiedostoon kirjoitettavan tekstin.
  2. Edelleen, convertDocumentToMarkdownissa kutsutaan asiakirjaobjektin menetelmiä ja ominaisuuksia etsimään ja korvaamaan asiaankuuluvat sanaominaisuudet vastaavalla GFM-kielen syntaksilla. Esim. Etsitään alaindeksejä sekä lihavoituja ja kursivoituja tekstejä. Sen jälkeen teksti korvataan GFM-koodilla. Ja lopuksi sanat tyylit poistetaan. Kaikki tämä tapahtuu täällä.
  3. Tämän jälkeen ristiviitteet korvataan. Tämä on kuitenkin hankalaa. Ensin kutsutaan toggleShowCodes-toimintoa. Tällä on samanlainen vaikutus kuin alt + F9: llä Word-asiakirjassa. Tämä korvaa kaikki asiakirjan ristiviitteet koodilla. Sen jälkeen, etsi ja korvaa menetelmä kutsutaan etsimään ja korvaamaan kaikki ristiviittaukset GFM tyyliin. Tässä "19 REF" välitetään argumenttina funktiolle. Tämä on tavallinen hakukriteeri kaikkien ristiviittausten löytämiselle Word-asiakirjasta. Viimeinkin korvaamisen jälkeen kutsutaan jälleen toggleShowCodes-toiminto palauttamaan asiakirja alkuperäiseen muotoonsa.
  4. Viimeinkin kutsutaan writeDocument-funktio, joka tekee päätyön. Se lukee asiakirjan kappaleittain ja etsii sitten vaihtokokoa käyttäen kappaleiden tyylit (kuten onko kyseessä otsikko tai taulukko, luettelokappale tai kuva). Löydettystä tyylistä riippuen haluttu teksti kirjoitetaan nyt MD-tiedostoon.

Sana tai kaksi kuvien upottamisesta: Kuvien upottaminen MD-tiedostoon on vähän hankalaa.

Ensin sinun on tallennettava kuvat git-arkistoon. Sitten linkki on annettava MD-tiedostossa upottamiseksi siihen. Syntaksi on! [Alt text] (polku / sisään / arkistossa / image1.jpg).

Nyt, jotta tämä linkki voidaan luoda automaattisesti kuvalle muunnettaessa sana MD-tiedostoksi, luodaan piilotettu teksti (heti kuvan jälkeen ilman tilaa), jonka sisältö on linkki itse. Ja sitten koodissa tämä piilotettu teksti riisutaan ja lisätään MD-tiedostoon.

Nyt saatat löytää todellisen koodin tehdä kaikki nämä asiat erittäin tylsiä, mutta tämä kaikki on Word-sovelluksen paljastaman sovellusliittymän mukaan. Joten älä huoli siitä. Voit ehdottomasti viitata koodiini tai TypeScriptin alkuperäiseen koodiin. Molemmat ovat hyvä alku seuraavalle projektillesi.

Hei odota!! Se on siinä. Teit sen loppuun asti? No sitten ? Onnittelut! ? Ja, jos pidit tästä artikkelista, osu siihen taputukseen? -painiketta alla. Se merkitsisi minulle paljon ja se auttaa muita ihmisiä näkemään tarinan. Kippis! ?