de Manish Bansal

Ce? De ce ar dori cineva să genereze un fișier MD dintr-un document Microsoft Word? Dacă acesta este primul gând pe care l-ați avut după ce ați citit acest titlu, atunci permiteți-mi să vă ofer un caz de utilizare puternic.

Luați în considerare o situație în care utilizați Git sau orice alt sistem de control al versiunilor (VCS) pentru sursele proiectului dvs., precum și pentru artefactele acestuia. Acum, la fel ca majoritatea proiectelor, decideți să utilizați Microsoft Word pentru documentare și să îl verificați în Git. Din nou, mai mulți membri ai echipei editează același document. După editare, se înregistrează documentul în depozit.

Acum, Git va putea să mențină istoricul documentului dvs. Cum veți putea privi modificările care au fost aduse documentului de la ultima verificare? Da, puteți utiliza modul de schimbare a pistelor Microsoft Word, dar nu este așa de dezordonat? Sau de dragul cerului, veți putea folosi utilitarul Git diff pentru a verifica rapid diferențele? Aș spune că nu.

Atunci care este soluția? Ar trebui să încetați să utilizați Microsoft Word pentru documentare? Sau ar trebui să treceți la un alt VCS?

Nu aș spune niciuna. Ce-ar fi să vă mențineți documentația în Microsoft Word? Apoi schimbați-l într-un fișier Markdown (MD) (în termeni simpli, un fișier text) în timpul fazei de construire și verificați? Dacă această soluție te entuziasmează, atunci continuă să citești.

Dar, înainte de a trece direct la conversie, permiteți-mi să vă spun mai întâi ce este exact un fișier de reducere.

Ce este un markdown sau un fișier MD?

Markdown este un limbaj de sintaxă care vizează citirea și scrierea ușoară a textului structurat. Mai mult, este ușor de învățat și necesită doar un editor de text pentru a crea un document.

Acum, există mai multe implementări ale limbajului (cum ar fi GFM aka Github aromat Markdown). Fiecare dintre aceste implementări are propriile îmbunătățiri și caracteristici care nu sunt neapărat compatibile între ele.

Fiecare implementare acceptă diverse caracteristici comune, cum ar fi paragrafe, ghilimele bloc, titluri și liste. Acest lucru ajută la menținerea textului într-un mod structurat precum Microsoft Word. Dar, în loc să utilizeze coduri binare interne, fișierele MD folosesc caractere text simplu pentru aceste caracteristici. Acest lucru face ca un fișier MD să fie un fișier text, dar nu un fișier binar ca un fișier docx.

De exemplu, în aroma de reducere a GitHub, iată diferitele caracteristici și moduri de a le reprezenta sub formă de text comparativ cu un document Word.

Cum se genereaza un fisier de reducere GitHub din Microsoft

Pentru avantajele detaliate ale fișierelor MD față de documentele Word, puteți consulta, de asemenea acest articol.

O.K! Sunt convins. Arată-mi codul.

Disclaimer: Acest proiect este inspirat din codul sursă TypeScript. În timp ce îl navigam, am găsit această idee de a converti un document Word într-un fișier MD. Puteți vedea codul sursă al acestuia aici.

Pentru simplitate, am eliminat câteva secțiuni de cod din depozitul meu. Codul original a fost menit să convertească documentația specificațiilor TypeScript într-un fișier MD. Acest fișier conține o mulțime de stiluri personalizate. Deci, după ce ați terminat cu acest articol, puteți parcurge foarte mult codul convertor TypeScript și puteți aprecia abilitățile sale de a efectua conversii mai complexe.

Codul complet menționat în acest articol poate fi consultat aici. Întregul cod poate fi împărțit în 3 secțiuni:

  1. Configurări Gulp.
  2. Executarea CScript.
  3. Funcția principală TypeScript

După cum sa menționat anterior, puteți converti un document Word într-un fișier MD în timpul fazei de construire. Acest lucru poate fi făcut de orice alergător de sarcini. Aici, am ales gulp.

În configurațiile Gulp, am definit 3 sarcini. Primul este să curățați directorul de construcție, care este destul de standard. Al doilea este să compilezi codul TypeScript. Și ultima este să apelați CScript pentru executarea JavaScript.

Ce este CScript?

CScript.exe (prezent în C: Windows System32) este un executabil bazat pe consolă pentru gazda de scriptare care este utilizată pentru a rula scripturile. Poate interpreta limbaje de scriptare precum VB Script sau JavaScript. În mod similar, avem WScript, dar este utilizat pentru aplicații Windows. În aceasta, consola nu este atașată. Deci, dacă aveți cerința de a crea o aplicație bazată pe consolă, putem folosi CScript.

Acum, în proiectul nostru, sarcina principală a CScript este de a oferi un mediu de execuție scriptului nostru, adică JavaScript. Acum, trebuie să vă gândiți, de ce nu am folosit nod în loc de CScript pentru a rula JavaScript-ul meu.

Ambele oferă un mediu de rulare pentru un JavaScript. CScript oferă suport inerent pentru tehnica modelului obiectelor componente Windows. Deci, dacă încercați să rulați acest script prin Node, veți primi o eroare ca aceasta.

var fileStream = ActiveXObject nou („ADODB.Stream”);

ReferenceError: ActiveXObject nu este definit

Acum, ce este o tehnică de modelare a obiectelor componente?

Modelul de obiecte componente este o tehnologie dezvoltată de Microsoft. Nu este un limbaj, ci un standard binar. Conform definiției,

Modelul obiectelor componente Microsoft (COM) este un sistem independent de platformă, distribuit, orientat pe obiecte, pentru a crea componente software binare care pot interacționa. COM este tehnologia de bază pentru Microsoft OLE (documente compuse), ActiveX (componente compatibile cu Internet), precum și altele.

În termeni simpli, obiectele COM sunt interfețe cu diferitele obiecte de execuție. (De aceea definiția are un termen numit „componente software binare”). Nu este un limbaj, ci o tehnică care este un limbaj de programare agnostic.

Singura cerință lingvistică pentru COM este că codul este generat într-un limbaj care poate crea structuri de indicatori. Fie în mod explicit sau implicit, apelați funcțiile prin pointeri. Limbaje orientate pe obiecte, cum ar fi C ++ și Smalltalk, oferă mecanisme de programare care simplifică implementarea obiectelor COM

După aceea, putem folosi orice alt limbaj precum Java, VB sau JavaScript pentru a interacționa cu acele obiecte COM. Acest lucru ne va oferi în continuare acces la aplicațiile de execuție. În cazul nostru, la aplicațiile Microsoft Word.

Deci, spuneți că nu putem folosi deloc nodul aici?

Nu, nu este adevărat. Putem folosi și Node în loc de CScript. Dar pentru a sprijini COM, va trebui să instalăm un alt pachet numit win32com pentru asistență COM. Detalii pot fi găsite aici.

Cod final

Acum, pentru a interacționa cu aplicația de cuvânt, au fost utilizate diferite API-uri. Și din moment ce folosim modelul de obiect COM, m-am referit la model de obiect cuvânt.

Word oferă sute de obiecte cu care puteți interacționa. Aceste obiecte sunt organizate într-o ierarhie care urmărește îndeaproape interfața cu utilizatorul. În partea de sus a ierarhiei se află obiectul Application. Acest obiect reprezintă instanța actuală a Word. Obiectul Application conține obiectele Document, Selection, Bookmark și Range. Fiecare dintre aceste obiecte are multe metode și proprietăți pe care le puteți accesa pentru a manipula și interacționa cu obiectul.

Acum, în scriptul nostru, am creat mai întâi un obiect de aplicație word utilizând ActiveXObject. Odată ce obiectul aplicației este obținut, obiectul document este creat prin trecerea numelui documentului (obținut din argumentele din linia de comandă a apelării cscript).

Acum, acesta reprezintă obiectul activ al documentului propriu-zis. Acest obiect este capabil să analizeze și să manipuleze documentul Word. Cu toate acestea, în cazul nostru de utilizare, trebuie doar să analizăm documentul și să scriem un fișier text.

Acest cod este foarte generic, care este utilizat pentru a converti caracteristicile de bază ale unui document Word, cum ar fi referințe încrucișate, liste, texte cu indicii, caractere aldine și italice etc. în format GFM. Cu toate acestea, puteți scrie propriul cod convertind stilurile personalizate ale documentului Word în formatul dorit.

Puteți găsi codul de dactilografiere propriu-zis aici. Codul este destul de ușor de citit. Mai jos sunt câteva aspecte importante ale acestuia:

  1. Primul, un obiect document este trecut la funcția convertDocumentToMarkdown care returnează textul care trebuie scris într-un fișier MD.
  2. Mai mult, în convertDocumentToMarkdown, metodele și proprietățile obiectului document sunt chemate pentru a găsi și a înlocui caracteristicile relevante ale cuvântului cu sintaxa limbajului GFM corespunzătoare. De exemplu, sunt căutate în primul rând indicele și textele aldine și cursive. După aceea, textul este înlocuit cu cod specific GFM. Și, în cele din urmă, cuvintele stiluri sunt eliminate. Toate acestea sunt făcute aici.
  3. După aceasta, sunt referințe încrucișate înlocuit. Cu toate acestea, acest lucru este dificil. În primul rând, se numește funcția toggleShowCodes. Acest lucru are un impact similar cu alt + F9 într-un document Word. Aceasta înlocuiește toate referințele încrucișate dintr-un document cu codul. După aceea, metoda de găsire și înlocuire este apelată pentru a găsi și înlocui toate referințele încrucișate cu stilul GFM. Aici, „19 REF” este transmis ca argument pentru o funcție. Acesta este un criteriu standard de căutare pentru găsirea tuturor referințelor încrucișate într-un document Word. În cele din urmă, după înlocuire, este apelată din nou funcția toggleShowCodes pentru a readuce documentul la forma sa originală.
  4. În sfârșit, se numește funcția writeDocument care face treaba principală. Citește documentul paragraf cu paragraf și apoi, folosind comutatorul de majuscule, caută stilurile paragrafelor (cum ar fi dacă este un titlu sau un tabel sau un paragraf de listă sau o imagine). Acum, în funcție de stilul găsit, textul dorit este scris în fișierul MD.

Un cuvânt sau două despre încorporarea imaginilor: Încorporarea imaginilor într-un fișier MD este un pic dificil.

Mai întâi, trebuie să stocați imaginile în depozitul dvs. git. Apoi, linkul trebuie să fie dat în fișierul MD pentru încorporare în acesta. Sintaxa este![alt text](cale / în / depozitul / imaginea1.jpg).

Acum, pentru a genera automat acest link pentru o imagine în timp ce convertiți cuvântul într-un fișier MD, se creează text ascuns (imediat după imagine fără spațiu) cu conținut ca link în sine. Și apoi în cod, acest text ascuns este eliminat și inserat în fișierul MD.

Acum, s-ar putea să găsiți codul propriu-zis pentru a face toate aceste lucruri foarte plictisitor, dar toate acestea sunt în conformitate cu API expus de aplicația Word. Deci, nu vă faceți griji în legătură cu asta. Puteți consulta cu siguranță codul meu sau codul original TypeScript. Ambele vor fi un bun start pentru următorul dvs. proiect.

Oh, așteptați!! Aia este. Ai reușit până la sfârșit? In regula, atunci ? Felicitări! ? Și, dacă ți-a plăcut acest articol, te rog să dai lovitura? butonul de mai jos. Ar însemna mult pentru mine și îi va ajuta pe ceilalți să vadă povestea. Noroc! ?