Как да генерирам файл за маркиране на GitHub от Microsoft Word с помощта на TypeScript

Какво? Защо някой би искал да генерира MD файл от Microsoft word документ? Ако това е първата мисъл, която сте имали, след като сте прочели това заглавие, позволете ми да ви дам сериозен пример.

Помислете за ситуация, при която използвате Git или друга система за контрол на версиите (VCS) за източниците на вашия проект, както и за неговите артефакти. Сега, както повечето проекти, решавате да използвате Microsoft word за документация и да я проверите в Git. Отново, множество членове на екипа редактират един и същ документ. След редактиране те проверяват документа в хранилището.

Сега Git ще може да поддържа историята на вашия документ. Как ще можете да гледате на промените, направени в документа, откакто сте го чекирали за последно? Да, можете да използвате режима за промяна на песента на Microsoft word, но това не е ли объркано? Или за бога, ще можете ли да използвате помощната програма Git diff, за да проверите бързо разликите? Бих казал, че не.

Тогава какво е решението? Трябва ли да спрете да използвате Microsoft Word за документация? Или трябва да преминете към някой друг VCS?

Не бих казал нито едното, нито другото. Какво ще кажете да поддържате документацията си в Microsoft word? След това го променете във файл с намалена стойност (MD) (в неспециализиран вид, текстов файл) по време на фазата на изграждане и регистрация? Ако това решение ви вълнува, продължете да четете.

Но преди да преминем направо към преобразуване, нека първо ви кажа какво точно представлява файлът за намаление.

Какво е намаление или MD файл?

Markdown е синтаксичен език, целящ лесно четене и писане на структуриран текст. Освен това е лесно да се научи и изисква само текстов редактор за създаване на документ.

Сега има множество реализации на езика (като GFM, известен още като Github ароматизиран Markdown). Всяко от тези внедрения има свои собствени подобрения и функции, които не са непременно съвместими помежду си.

Всяка реализация поддържа различни общи функции като абзаци, блокови цитати, заглавия и списъци. Това помага за поддържането на текст по структуриран начин като Microsoft Word. Но вместо да използват вътрешни двоични кодове, MD файловете използват текстови символи за тези функции. Това прави MD файл текстов файл, но не и двоичен файл като docx файл.

Например, в аромата за намаление на GitHub, тук са различните функции и начини за представянето им под формата на текст в сравнение с документ с думи.

За подробни предимства на MD файловете пред word документи можете също да се обърнете към тази статия.

ДОБРЕ! Убедена съм. Покажи ми кода.

Отказ от отговорност: Този проект е вдъхновен от изходния код на TypeScript. Докато го разглеждах, намерих тази идея за конвертиране на документ с думи в MD файл. Можете да видите неговия изходен код тук.

За простота премахнах няколко раздела с код в хранилището си. Оригиналният код е предназначен да конвертира документацията за спецификации на TypeScript в MD файл. Този файл съдържа много персонализирани стилове. Така че, след като приключите с тази статия, можете много да преминете през TypeScript кода на конвертора и да оцените способностите му да извършва по-сложни преобразувания.

Пълният код, споменат в тази статия, може да бъде посочен тук. Целият код може да бъде разделен на 3 раздела:

  1. Конфигурации на глътка.
  2. Изпълнение на CScript.
  3. Основна функция на TypeScript

Както беше посочено по-рано, можете да конвертирате документ с думи в MD файл по време на фазата на изграждане. Това може да направи всеки бегач на задачи. Ето, избрах глътка.

В конфигурациите на Gulp съм дефинирал 3 задачи. Първият е да почистите директорията за изграждане, която е доста стандартна. Второто е компилиране на TypeScript кода. И последното е да извикате CScript за изпълнение на JavaScript.

Какво е CScript?

CScript.exe (присъства в C: \ Windows \ System32) е конзолно изпълним файл за скриптов хост, който се използва за стартиране на скриптове. Той може да тълкува скриптови езици като VB Script или JavaScript. По същия начин имаме WScript, но той се използва за Windows приложения. При това конзолата не е прикрепена. Така че, ако имате изискване за създаване на конзолно приложение, можем да използваме CScript.

Сега в нашия проект основната работа на CScript е да осигури среда за изпълнение на нашия скрипт, т.е. JavaScript. Сега, сигурно си мислите, защо не съм използвал node вместо CScript, за да стартирам JavaScript.

И двете предоставят среда за изпълнение за JavaScript. CScript осигурява присъща поддръжка за техниката на обектния модел на компонентите на Windows. Така че, ако се опитате да стартирате този скрипт чрез Node, ще получите грешка като тази.

var fileStream = нов ActiveXObject (“ADODB.Stream”); ReferenceError: ActiveXObject не е дефиниран

Какво представлява техниката на компонентния обектен модел?

Компонентният обектен модел е технология, разработена от Microsoft. Това не е език, а двоичен стандарт. Според дефиницията,

Microsoft Component Object Model (COM) е независима от платформа, разпределена, обектно-ориентирана система за създаване на двоични софтуерни компоненти, които могат да си взаимодействат. COM е основната технология за OLE на Microsoft (съставни документи), ActiveX (компоненти, поддържащи интернет), както и други.

В неспециализиран смисъл COM обектите са интерфейси към различните обекти за изпълнение. (Ето защо дефиницията има термин, наречен „двоични софтуерни компоненти“). Това не е език, а техника, която е агностична на езика за програмиране.

Единственото езиково изискване за COM е, че кодът се генерира на език, който може да създава структури от указатели. Изрично или неявно извиквайте функции чрез указатели. Обектно-ориентираните езици като C ++ и Smalltalk предоставят механизми за програмиране, които опростяват внедряването на COM обекти

След това можем да използваме всеки друг език като Java, VB или JavaScript за взаимодействие с тези COM обекти. Това допълнително ще ни даде достъп до приложения за изпълнение. В нашия случай - към приложенията за дума на Microsoft.

И така, казвате ли, че изобщо не можем да използваме Node?

Не, това не е вярно. Можем да използваме Node и вместо CScript. Но за да поддържаме COM, ще трябва да инсталираме друг пакет, наречен win32com за COM поддръжка. Подробности можете да намерите тук.

Окончателен код

Сега, за да взаимодействаме с приложението на думи, бяха използвани различни API. И тъй като ние използваме обектния модел COM, се позовах на думата обектен модел.

Word предоставя стотици обекти, с които можете да взаимодействате. Тези обекти са организирани в йерархия, която следи отблизо потребителския интерфейс. В горната част на йерархията е обектът Application. Този обект представлява текущия екземпляр на Word. Обектът Application съдържа обектите Document, Selection, Bookmark и Range. Всеки от тези обекти има много методи и свойства, до които имате достъп, за да манипулирате и да взаимодействате с обекта.

Сега, в нашия скрипт, първо създадохме обект на приложение на дума, използвайки ActiveXObject. След като обектът на приложението бъде получен, обектът на документ се създава чрез предаване на името на документа (получено от аргументи от командния ред на извикване на cscript).

Сега това представлява активния обект на действителния документ. Този обект може да анализира, както и да манипулира думата документ. В нашия случай на употреба обаче трябва само да анализираме документа и да напишем текстов файл.

Този код е много общ, който се използва за конвертиране на много основни характеристики на документ с думи като кръстосани препратки, списъци, текстове с индекс, получер и курсив и т.н. във формат GFM. Можете обаче да напишете свой собствен код, превръщайки вашите персонализирани стилове на словния документ в желания формат.

Можете да намерите действителния код на машинопис тук. Кодът е доста лесен за четене. По-долу има няколко основни акцента от него:

  1. Първо, обектът на документ се предава на функцията convertDocumentToMarkdown, която връща текста, който трябва да бъде записан в MD файл.
  2. Освен това в convertDocumentToMarkdown се извикват методи и свойства на обекта на документа, за да се намерят и заменят съответните функции на думата със съответния синтаксис на езика GFM. Например първо се търсят текстове с индекс и получер текст и курсив. След това текстът се заменя със специфичен код на GFM. И накрая, стиловете на думите се премахват. Всичко това се прави тук.
  3. След това кръстосаните препратки се заменят. Това обаче е сложно. Първо се извиква функцията toggleShowCodes. Това има подобно въздействие като alt + F9 в текстов документ. Това замества всички препратки в документ с кода. След това се извиква метод за намиране и замяна, за да се намерят и заменят всички препратки със стил GFM. Тук „19 REF“ се предава като аргумент на функция. Това е стандартен критерий за търсене за намиране на всички препратки в документ с думи. Накрая, след подмяната, отново се извиква функцията toggleShowCodes, за да върне документа в първоначалната му форма.
  4. Накрая се извиква функцията writeDocument, която върши основната работа. Чете документа по абзац на документа и след това, използвайки превключвател, търси стиловете на абзаците (като дали е заглавие или таблица, абзац от списък или изображение). Сега, в зависимост от намерения стил, желаният текст се записва в MD файла.

Дума или две за вграждането на изображения: Вграждането на изображения в MD файл е малко сложно.

Първо, трябва да съхраните изображенията във вашето git хранилище. След това връзката трябва да бъде дадена в MD файла за вграждане в нея. Синтаксисът е! [Alt text] (path / in / the / repository / image1.jpg).

Сега, за да се генерира автоматично тази връзка за изображение, докато се преобразува дума в MD файл, се създава скрит текст (непосредствено след изображението, без място) със съдържание като самата връзка. И след това в кода този скрит текст се отстранява и се вмъква в MD файла.

Сега може да откриете, че действителният код за извършване на всички тези неща е много досаден, но това е всичко според API, изложен от приложението Word. Така че не се притеснявайте за това. Определено можете да се обърнете към моя код или оригиналния код на TypeScript. И двете ще бъдат добър старт за следващия ви проект.

О, чакайте !! Това е. Успяхте до края? Добре тогава ? Честито! ? И, ако тази статия ви е харесала, моля, натиснете това пляскане? бутон по-долу. Това би означавало много за мен и ще помогне на другите хора да видят историята. Наздраве! ?