Как создать файл уценки GitHub из Microsoft Word с помощью TypeScript

1656515654 kak sozdat fajl uczenki github iz microsoft word s pomoshhyu

от Маниш Бансал

Что? Почему необходимо создать файл MD из документа Microsoft Word? Если это первое мнение, возникшее у вас после прочтения этого названия, позвольте мне дать вам мощный вариант использования.

Рассмотрим ситуацию, когда вы используете Git или любую другую систему контроля версий (VCS) для источников вашего проекта, а также его артефактов. Теперь, как и большинство проектов, вы решили использовать Microsoft Word для документации и проверить его в Git. Снова несколько членов команды редактируют один и тот же документ. После редактирования они заносят документ в хранилище.

Теперь Git сможет поддерживать историю вашего документа. Как вы можете просмотреть изменения, внесенные в документ с момента последней регистрации? Да, вы можете использовать режим смены дорожки Microsoft word, но разве это не беспорядочно? Или, ради Бога, сможете ли вы воспользоваться утилитой Git diff, чтобы быстро проверить отличия? Я бы сказал, нет.

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

Я бы сказал, нет. Как насчет сохранения своей документации в Microsoft Word? Затем изменить его на файл уценки (MD) (как неспециалист, текстовый файл) на этапе сборки и зарегистрироваться? Если это решение возбуждает вас, продолжайте читать.

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

Что такое уценка или MD-файл?

Markdown – язык синтаксиса, предназначенный для легкого чтения и написания структурированного текста. Кроме того, его легко научиться, и для создания документа требуется только текстовый редактор.

Теперь существует несколько реализаций этого языка (например, GFM aka Github с ароматом Markdown). Каждая из этих реализаций имеет собственные усовершенствования и функции, которые не обязательно совместимы друг с другом.

Каждая реализация поддерживает различные общие функции, такие как абзацы, блоковые кавычки, заголовки и списки. Это помогает поддерживать текст в структурированном виде, как в Microsoft Word. Но вместо использования внутренних двоичных кодов MD-файлы используют для этих функций символы обычного текста. Это делает файл MD текстовым, но не двоичным, как файл docx.

К примеру, в разработке GitHub представлены различные функции и способы представления их в виде текста по сравнению с текстовым документом.

EmrHeOtVuSp1R-hU7j6UqWwzB9r7DhCjGY0Y

Чтобы узнать больше о преимуществах MD-файлов перед документами Word, вы также можете обратиться к этой статье.

В ПОРЯДКЕ! я убежден. Покажи мне код.

Отказ от ответственности: этот проект вдохновлен исходным кодом TypeScript. Просматривая его, я нашел идею преобразования документа Word в файл MD. Вы можете увидеть его исходный код здесь.

Для простоты я удалил несколько разделов кода в своем репозитории. Оригинальный код преследовал цель превратить документацию из спецификации TypeScript в файл MD. Этот файл содержит много настроенных стилей. Итак, закончив эту статью, вы сможете ознакомиться с кодом конвертера TypeScript и оценить его способность выполнять более сложные преобразования.

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

  1. Настройки Gulp.
  2. Выполнение CScript.
  3. Основная функция TypeScript

Как было сказано ранее, вы можете преобразовать документ Word в файл MD на этапе сборки. Это может сделать любой бегун задач. Здесь я выбрал gulp.

В конфигурациях Gulp я определил три задачи. Во-первых, очистить каталог сборки, достаточно стандартный. Во-вторых, скомпилировать код 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 = new ActiveXObject(«ADODB.Stream»);

ReferenceError: ActiveXObject не определен

Теперь что такое техника компонентной объектной модели?

Компонентная объектная модель – это технология, разработанная Microsoft. Это не язык, а двоичный стандарт. Согласно определению,

Объектная модель компонентов Microsoft (COM) – это независимая от платформы распределенная объектно-ориентированная система для создания бинарных программных компонентов, которые могут взаимодействовать. COM является базовой технологией для Microsoft OLE (составленных документов), ActiveX (компонентов с поддержкой Интернета) и других.

С точки зрения неспециалиста, объекты COM являются интерфейсами к разным объектам среды выполнения. (Вот почему в определении есть термин, который называется «Бинарные программные компоненты»). Это не язык, а техника, не зависящая от языка программирования.

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

После этого мы можем использовать любой другой язык, например Java, VB или JavaScript, для взаимодействия с этими объектами COM. Это предоставит нам доступ к приложениям во время выполнения. В нашем случае к программам Microsoft Word.

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

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

Окончательный код

Теперь для взаимодействия с приложением Word используются разные API. И поскольку мы используем объектную модель COM, я ссылался на слово объектную модель.

Word дает сотни объектов, с которыми можно взаимодействовать. Эти объекты организованы в иерархию, точно соответствующую пользовательскому интерфейсу. В верхней части иерархии находится объект Application. Этот объект представляет текущий экземпляр Word. Объект Application содержит объекты «Документ», «Выбор», «Закладка» и «Диапазон». Каждый из этих объектов имеет множество методов и свойств, к которым вы можете получить доступ, чтобы манипулировать и взаимодействовать с объектом.

Теперь в нашем сценарии мы впервые создали объект текстовой программы с помощью ActiveXObject. Как только объект программы был получен, объект документа создается путем передачи имени документа (полученного из аргументов командной строки вызова cscript).

Теперь это представляет активный объект фактического документа. Этот объект способен анализировать и манипулировать документом Word. Однако в нашем случае нам нужно только проанализировать документ и написать текстовый файл.

Этот код очень общий, который используется для преобразования основных функций текстового документа, таких как перекрестные ссылки, списки, нижний индекс, жирный и курсив и т.п., в формат GFM. Однако вы можете написать собственный код, преобразуя настроенные стили документа Word в нужный формат.

Настоящий машинописный код можно найти здесь. Код достаточно просто читается. Ниже приведено несколько основных его моментов:

  1. Сначала объект документа передается функции convertDocumentToMarkdown, которая возвращает текст для записи в MD-файл.
  2. Кроме того, в convertDocumentToMarkdown вызываются методы и свойства объекта документа, чтобы найти и заменить соответствующие элементы слова соответствующим синтаксисом языка GFM. К примеру, сначала выполняется поиск подстрочного, полужирного и курсивного текстов. После этого текст заменяется особым кодом GFM. И, наконец, стили слов удаляются. Все это здесь делается.
  3. После этого перекрестные ссылки заменяются. Однако, это непросто. Первоначально вызывается функция toggleShowCodes. Это оказывает подобное влияние, как alt+F9 в документе Word. Это заменяет все перекрестные ссылки в документе кода. После этого вызывается метод find and replace для поиска и замены всех перекрестных ссылок на стиль GFM. Здесь «19 REF» передается как аргумент функции. Это стандартный критерий поиска для поиска всех перекрестных ссылок в Word. Наконец, после замены снова вызывается функция toggleShowCodes, чтобы вернуть документ в исходный вид.
  4. Наконец, вызывается функция writeDocument, выполняющая основную работу. Он читает документ абзаца по абзацу, а затем, используя регистр, ищет стили абзацев (например, если это заголовок, таблица, абзац списка или изображения). Теперь в зависимости от найденного стиля нужный текст записывается в MD-файл.

Несколько слов о встраивании изображений: Встраивание изображений в файл MD несколько сложно.

Во-первых, вам нужно сохранить изображение в вашем хранилище git. Затем в файле MD необходимо указать ссылку для встраивания в него. Синтаксис таков![alt text](путь/в/хранилище/image1.jpg).

Теперь, чтобы автоматически сгенерировать эту ссылку для изображения при преобразовании word в файл MD, создается скрытый текст (сразу после изображения без пробела) с содержимым в качестве самой ссылки. Затем в коде этот скрытый текст удаляется и вставляется в файл MD.

Теперь вы можете обнаружить фактический код для выполнения всех этих вещей очень утомительным, но это все в соответствии с API, предоставленным программой Word. Поэтому не беспокойтесь об этом. Вы точно можете ссылаться на мой код или исходный код TypeScript. Оба станут хорошим началом для вашего следующего проекта.

Жди!! Вот и все. Вы дожили до конца? Ну хорошо ? Поздравляю! ? И если вам понравилась эта статья, пожалуйста, нажмите этот хлопок? кнопку ниже. Для меня это означало бы многое, и это поможет другим людям увидеть историю. На здоровье! ?

Добавить комментарий

Ваш адрес email не будет опубликован.