Kaip sukurti „GitHub“ žymėjimo failą iš „Microsoft Word“ naudojant „TypeScript“

Ką? Kodėl reikėtų norėti sugeneruoti MD failą iš „Microsoft Word“ dokumento? Jei tai pirmoji mintis, kilusi perskaičius šį pavadinimą, leiskite man pateikti tvirtą naudojimo atvejį.

Apsvarstykite situaciją, kai savo projekto šaltiniams, taip pat artefaktams, naudojate „Git“ ar bet kurią kitą versijų valdymo sistemą (VCS). Dabar, kaip ir dauguma projektų, nusprendžiate naudoti „Microsoft“ žodį dokumentacijai ir patikrinti jį „Git“. Vėlgi, keli komandos nariai taiso tą patį dokumentą. Po redagavimo jie patikrina dokumentą į saugyklą.

Dabar „Git“ galės išlaikyti jūsų dokumento istoriją. Kaip galėsite pažvelgti į pakeitimus, kurie buvo padaryti po paskutinio jo patikrinimo? Taip, galite naudoti „Microsoft Word“ takelio keitimo režimą, bet argi tai netvarkinga? Arba dėl dangaus, ar galėsite naudoti „Git diff“ įrankį, kad greitai patikrintumėte skirtumus? Sakyčiau, ne.

Tada koks sprendimas? Ar turėtumėte nustoti naudoti „Microsoft Word“ dokumentacijai? Arba turėtumėte pereiti prie kito VCS?

Aš nepasakyčiau nei. Kaip būtų, jei dokumentaciją išlaikytumėte „Microsoft Word“? Tada kūrimo etape pakeiskite jį į žymėjimo (MD) failą (nespecialistiškai - teksto failą) ir užsiregistruosite? Jei šis sprendimas jus jaudina, toliau skaitykite.

Bet prieš pereidamas tiesiai į konversiją, leiskite pirmiausia pasakyti, kas tiksliai yra žymėjimo failas.

Kas yra žymėjimas arba MD failas?

Markdown yra sintaksės kalba, skirta lengvai skaityti ir rašyti struktūrinį tekstą. Be to, ją lengva išmokti, o norint sukurti dokumentą reikia tik teksto redaktoriaus.

Dabar yra keli kalbos variantai (pvz., „GFM“, dar žinomas kaip „Github“ skonio „Markdown“). Kiekvienas iš šių diegimų turi savo patobulinimų ir savybių, kurios nebūtinai yra suderinamos viena su kita.

Kiekvienas diegimas palaiko įvairias bendras funkcijas, tokias kaip pastraipos, blokinės citatos, antraštės ir sąrašai. Tai padeda išlaikyti tekstą struktūrizuotu būdu, pvz., „Microsoft Word“. Tačiau užuot naudoję vidinius dvejetainius kodus, MD failai šioms funkcijoms naudoja paprasto teksto simbolius. Tai daro MD failą tekstiniu, bet ne dvejetainiu, kaip docx failu.

Pvz., „GitHub“ ženklinime pateikiami įvairūs jų pateikimo teksto pavidalu ir būdai, palyginti su žodiniu dokumentu.

Norėdami sužinoti apie išsamius MD failų pranašumus, palyginti su „Word“ dokumentais, taip pat galite perskaityti šį straipsnį.

GERAI! Esu įsitikinęs. Parodyk man kodą.

Atsakomybės apribojimas: šį projektą įkvėpė „TypeScript“ šaltinio kodas. Naršydamas radau šią idėją konvertuoti žodinį dokumentą į MD failą. Čia galite pamatyti jo šaltinio kodą.

Kad būtų paprasčiau, iš saugyklos pašalinau kelias kodo dalis. Originalus kodas buvo skirtas konvertuoti „TypeScript“ specifikacijos dokumentus į MD failą. Šiame faile yra daug pritaikytų stilių. Taigi, kai baigsite šį straipsnį, galite labai daug pereiti prie „TypeScript“ keitiklio kodo ir įvertinti jo galimybes atlikti sudėtingesnes konversijas.

Visas šiame straipsnyje minimas kodas gali būti nurodytas čia. Visą kodą galima suskirstyti į 3 dalis:

  1. „Gulp“ konfigūracijos.
  2. CScript vykdymas.
  3. „TypeScript“ pagrindinė funkcija

Kaip minėta anksčiau, kūrimo etape galite konvertuoti žodinį dokumentą į MD failą. Tai gali padaryti bet kuris bėgikas. Čia aš pasirinkau gurkšnį.

„Gulp“ konfigūracijose aš apibrėžiau 3 užduotis. Pirmasis yra išvalyti pastatymo katalogą, kuris yra gana standartinis. Antra - surinkti „TypeScript“ kodą. Paskutinis yra paskambinti CScript, kad būtų vykdoma „JavaScript“.

Kas yra CScript?

CScript.exe (yra C: \ Windows \ System32) yra konsolės vykdomasis scenarijų pagrindinio kompiuterio vykdomasis failas, naudojamas scenarijams paleisti. Jis gali interpretuoti tokias scenarijų kalbas kaip „VB Script“ ar „JavaScript“. Panašiai turime ir „WScript“, tačiau jis naudojamas „Windows“ programoms. Šiuo atveju konsolė nėra pritvirtinta. Taigi, jei jums reikia sukurti konsole pagrįstą programą, galime naudoti CScript.

Dabar mūsų projekte pagrindinis „CScript“ darbas yra užtikrinti scenarijaus vykdymo laiko aplinką, ty „JavaScript“. Dabar jūs turėtumėte galvoti, kodėl aš nenaudojau mazgo, o ne CScript, norėdamas paleisti „JavaScript“.

Abi suteikia „JavaScript“ vykdymo laiko aplinką. „CScript“ suteikia būdingą „Windows“ komponentų objektų modelio technikos palaikymą. Taigi, jei bandysite paleisti šį scenarijų per „Node“, gausite tokią klaidą.

var fileStream = new ActiveXObject („ADODB.Stream“); „ReferenceError“: „ActiveXObject“ nėra apibrėžtas

Kas yra komponentinio objekto modelio technika?

Komponentinis objekto modelis yra „Microsoft“ sukurta technologija. Tai ne kalba, o dvejetainis standartas. Pagal apibrėžimą,

„Microsoft Component Object Model“ (COM) yra nuo platformos nepriklausoma, paskirstyta, į objektą orientuota sistema, skirta kurti dvejetainius programinės įrangos komponentus, kurie gali sąveikauti. COM yra pagrindinė „Microsoft“ OLE (sudėtiniai dokumentai), „ActiveX“ (internetiniai komponentai) ir kitų technologijų technologija.

Kalbant paprastai, COM objektai yra sąsajos su įvairiais vykdymo laiko objektais. (Štai kodėl apibrėžime yra terminas, vadinamas „dvejetainiais programinės įrangos komponentais“). Tai ne kalba, o technika, kuri programuoja kalbos agnostiką.

Vienintelis COM reikalavimas dėl kalbos yra tas, kad kodas generuojamas kalba, kuri gali sukurti rodyklių struktūras. Tiesiogiai ar netiesiogiai iškvieskite funkcijas naudodamiesi rodyklėmis. Į objektą orientuotos kalbos, tokios kaip C ++ ir „Smalltalk“, suteikia programavimo mechanizmus, kurie supaprastina COM objektų įgyvendinimą

Po to mes galime naudoti bet kurią kitą kalbą, pvz., „Java“, „VB“ ar „JavaScript“, kad galėtume sąveikauti su tais COM objektais. Tai dar labiau suteiks mums prieigą prie vykdymo laiko programų. Mūsų atveju - „Microsoft Word“ programoms.

Taigi, ar jūs sakote, kad mes apskritai negalime naudoti „Node“?

Ne, tai netiesa. Taip pat vietoj CScript galime naudoti „Node“. Tačiau norėdami palaikyti COM, turėsime įdiegti kitą paketą, vadinamą win32com, kad galėtume palaikyti COM. Išsamią informaciją galite rasti čia.

Galutinis kodas

Dabar, norint sąveikauti su žodžių programa, buvo naudojamos įvairios API. Kadangi mes naudojame COM objekto modelį, aš kreipiausi į žodį objekto modelis.

„Word“ pateikia šimtus objektų, su kuriais galite bendrauti. Šie objektai yra suskirstyti į hierarchiją, kuri atidžiai seka vartotojo sąsają. Hierarchijos viršuje yra „Application“ objektas. Šis objektas reiškia dabartinį „Word“ egzempliorių. Programos objekte yra objektai Dokumentas, Pasirinkimas, Žymė ir Diapazonas. Kiekvienas iš šių objektų turi daug metodų ir savybių, kurias galite pasiekti norėdami manipuliuoti ir sąveikauti su objektu.

Dabar, naudodami „ActiveXObject“, savo scenarijuje pirmiausia sukūrėme žodžio programos objektą. Gavus programos objektą, dokumento objektas sukuriamas perduodant dokumento pavadinimą (gautą iš „cscript“ iškvietimo komandinės eilutės argumentų).

Tai reiškia aktyvų faktinio dokumento objektą. Šis objektas gali analizuoti ir manipuliuoti žodžiu „dokumentas“. Tačiau mūsų naudojimo atveju mums reikia tik išanalizuoti dokumentą ir parašyti teksto failą.

Šis kodas yra labai bendras, naudojamas konvertuoti labai pagrindines žodinio dokumento ypatybes, tokias kaip kryžminės nuorodos, sąrašai, indekso tekstai, pusjuodis ir kursyvas ir kt. Į GFM formatą. Tačiau galite parašyti savo kodą, konvertuodami pritaikytus žodžio dokumento stilius į norimą formatą.

Tikrąjį mašinraščio kodą rasite čia. Kodas yra gana lengvai skaitomas. Toliau pateikiami keli svarbiausi jo akcentai:

  1. Pirmiausia, dokumento objektas perduodamas funkcijai convertDocumentToMarkdown, kuri grąžina MD faile parašytą tekstą.
  2. Be to, programoje convertDocumentToMarkdown, norint nustatyti ir pakeisti atitinkamas žodžio ypatybes atitinkama GFM kalbos sintakse, iškviečiami dokumento objekto metodai ir ypatybės. Pvz., Pirmiausia ieškoma subtitrų, pusjuodžių ir kursyvinių tekstų. Po to tekstas pakeičiamas konkrečiu GFM kodu. Galiausiai, žodžių stiliai pašalinami. Visa tai daroma čia.
  3. Po to kryžminės nuorodos pakeičiamos. Tačiau tai keblu. Pirmiausia iškviečiama funkcija toggleShowCodes. Tai turi panašų poveikį kaip „Alt“ + F9 „Word“ dokumente. Tai pakeičia visas kryžmines nuorodas dokumente kodu. Po to, norint rasti ir pakeisti visas kryžmines nuorodas GFM stiliumi, reikia rasti ir pakeisti metodą. Čia „19 REF“ perduodama kaip argumentas funkcijai. Tai yra standartinis paieškos kriterijus norint rasti visas kryžmines nuorodas žodiniame dokumente. Pagaliau, pakeitus, vėl iškviečiama funkcija toggleShowCodes, kad dokumentas būtų grąžintas į pradinę formą.
  4. Pagaliau iškviečiama funkcija writeDocument, kuri atlieka pagrindinį darbą. Jis skaito dokumentą kiekviena pastraipa ir, naudodamas jungiklius, ieško pastraipų stilių (pavyzdžiui, jei tai antraštė, lentelė, sąrašo pastraipa ar vaizdas). Dabar, atsižvelgiant į rastą stilių, norimas tekstas įrašomas į MD failą.

Žodis ar du apie vaizdų įdėjimą: įterpti vaizdus į MD failą yra šiek tiek keblu.

Pirmiausia turite saugoti vaizdus savo „git“ saugykloje. Tada nuorodą reikia pateikti MD faile, kad ją būtų galima įterpti. Sintaksė yra! [Alt text] (kelias / į / saugykloje / image1.jpg).

Dabar, norint automatiškai sugeneruoti šią nuorodą vaizdui konvertuojant žodį į MD failą, sukuriamas paslėptas tekstas (iškart po paveikslėlio be vietos), kurio turinys yra pati nuoroda. Tada kode šis paslėptas tekstas pašalinamas ir įterpiamas į MD failą.

Dabar jums gali pasirodyti, kad tikrasis kodas visoms šioms užduotims atlikti yra labai varginantis, tačiau visa tai atitinka API, kurią atskleidžia „Word“ programa. Taigi nesijaudinkite dėl to. Jūs tikrai galite nurodyti mano kodą arba „TypeScript“ originalų kodą. Abi bus gera pradžia jūsų kitam projektui.

O palauk!! Viskas. Jūs tai padarėte iki galo? Gerai tada ? Sveikiname! ? Ir, jei jums patiko šis straipsnis, prašau paspausti tą plojimą? mygtuką. Tai man reikštų daug ir padės kitiems žmonėms pamatyti istoriją. Cheers! ?