Як згенерувати файл розмітки 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 Markous). Кожна з цих реалізацій має власні вдосконалення та функції, які не обов'язково сумісні між собою.

Кожна реалізація підтримує різні загальні функції, такі як абзаци, блок-цитати, заголовки та списки. Це допомагає підтримувати текст у структурованому вигляді, як Microsoft Word. Але, замість використання внутрішніх двійкових кодів, файли MD використовують символи простого тексту для цих функцій. Це робить файл MD текстовим, але не двійковим файлом, як файл docx.

Наприклад, у смаку знижки GitHub, наведено різні особливості та способи їх подання у вигляді тексту у порівнянні з текстовим документом.

Детальні переваги файлів MD перед документами Word можна також переглянути в цій статті.

В ПОРЯДКУ! Я переконаний. Покажи мені код.

Застереження: Цей проект натхненний вихідним кодом TypeScript. Переглядаючи його, я знайшов цю ідею перетворення документа Word у файл MD. Ви можете побачити його вихідний код тут.

Для простоти я видалив кілька розділів коду зі свого сховища. Оригінальний код мав на меті перетворити специфікацію TypeScript у файл MD. Цей файл містить безліч індивідуальних стилів. Отже, коли ви закінчите з цією статтею, ви дуже зможете переглянути код конвертера TypeScript і оцінити його можливості виконувати більш складні перетворення.

Повний код, згаданий у цій статті, можна переглянути тут. Весь код можна розділити на 3 розділи:

  1. Конфігурації ковтка.
  2. Виконання CScript.
  3. Основна функція TypeScript

Як було сказано раніше, ви можете перетворити документ Word у файл 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”); Помилка ReferenceEr: ActiveXObject не визначено

Тепер, що таке техніка компонентної об'єктної моделі?

Компонентна об'єктна модель - це технологія, розроблена корпорацією Майкрософт. Це не мова, а бінарний стандарт. Відповідно до визначення,

Об'єктна модель Microsoft (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 у текстовому документі. Це замінює всі перехресні посилання в документі кодом. Після цього викликається метод find and replace для пошуку та заміни всіх перехресних посилань стилем GFM. Тут “19 REF” передається як аргумент функції. Це стандартний критерій пошуку для пошуку всіх перехресних посилань у текстовому документі. Нарешті, після заміни знову викликається функція toggleShowCodes, щоб повернути документ у початкову форму.
  4. Нарешті, викликається функція writeDocument, яка виконує основну роботу. Він читає документ абзац за абзацом, а потім, використовуючи регістр перемикача, шукає стилі абзаців (наприклад, якщо це заголовок, таблиця, абзац списку чи зображення). Тепер, залежно від знайденого стилю, потрібний текст записується у файл MD.

Слово-два про вбудовування зображень: Вбудовування зображень у файл MD трохи складно.

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

Тепер для того, щоб автоматично згенерувати це посилання для зображення під час перетворення слова у файл MD, створюється прихований текст (відразу після зображення без пробілу) із вмістом як самим посиланням. А потім у коді цей прихований текст видаляється та вставляється у файл MD.

Тепер вам може здатися, що фактичний код, щоб зробити все це, дуже втомливим, але це все згідно з API, виставленим додатком Word. Тож не переживайте з цього приводу. Ви можете точно вказати мій код або оригінальний код TypeScript. І те, і інше стане хорошим початком для вашого наступного проекту.

Чекай!! Це все. Ви дожили до кінця? Тоді гаразд ? Вітаємо! ? І, якщо вам сподобалась ця стаття, будь ласка, натисніть цей хлопок? кнопку нижче. Для мене це мало б значити, і це допоможе іншим людям побачити історію. На здоров’я! ?