Содержание
Давно ничего не писал. Много новых тем, много мыслей, всё никак не соберусь. Вот, наконец, собрался. Итак, сегодня у нас рассматривается конвертация текстовых форматов. Казалось бы – зачем это вообще кому-либо может понадобиться? Сейчас поясню.
Компьютерная документация
Айтишники поймут меня, если я скажу, как плохо, когда все (множество) сервисов замыкаются на одного конкретного человека и никто кроме него не может разобраться в случае какого-либо сбоя или изменения настроек. Просто потому что этот человек данный сервис устанавливал и конфигурировал, забарывал всплывающие баги и ошибки. И теперь навечно остаётся привязан к нему.
Решением в этом случае может стать создание соответствующих инструкций и сопутствующей документации, поясняющей особенности установки, настройки, конфигурации того или иного сервиса. Создавать документацию или нет – вопрос лично каждого. Но я уже столкнулся с тем, что порой хочется сказать что-то типа RTFM!, а вот тех самых M в природе не существует (ну либо нужно опять собирать по крупицам по сети).
Предположим, что мы определились, что документация нам нужна. В каком виде её составлять? В одной из предыдущих статей я уже писал, что неплохим вариантом будет являться внутренняя WIKI. Вещь неплохая, даже пригождалась пару раз. Но писать в неё документацию может показаться утомительно.
Мне привычно писать текст в Word, т.к. там есть какое-никакое форматирование. Прежде всего это изображения, фрагменты кода, заголовки различных уровней. Но использовать Word для таких непритязательных хотелок весьма излишне, поэтому я озаботился поиском такого текстового редактора, который бы одновременно и был простым, минималистичным и в то же время поддерживал форматирование, даже самое простое. А, самое главное, чем больше сейчас читаю о Git, тем больше хочется его везде внедрить, но работать в Git с DOCX-форматом несколько странно, поэтому нужен именно текстовый редактор, который при случае легко можно перевести в любой формат.
Markdown
Сосвем недавно открыл для себя этот замечательный язык разметки. Он прост и лаконичен, а тексты, оформленные по md – достаточно легко читаются как в специальных средствах, так и в обычном блокноте. Всё форматирование задаётся короткими [сочетаниями] спецсимволами, поэтому там всё-таки больше информации, чем разметки (чего нельзя сказать, например о HTML, где объём тегов и атрибутов достаточно велик, он так же избыточен, как и общий случай XML).
Для теста можете скачать редактор Typora и попробовать понабирать тексты.
Для оформления заголовка – его нужно обрамить в символы “#” с каждой стороны. Для первого уровня заголовка – по одной решётке. Для второго – по две и т.д. Код обрамляется в обратную кавычку. Вот пример разметки:
А вот так выглядит размеченный текст:
Это фрагмент из документации на настройку OpenVPN-сервера. Самое приятное, что текст в md-формате отлично жмётся архиваторами и скармливается Git-у (можно смотреть diff историю изменений и т.д.). Пока выберу для себя этот формат разметки. При желании можно вставлять ссылки, картинки, таблицы – всё довольно минималистично.
А что, если нужен другой формат?
Ну допустим, написали мы крутую инструкцию. Как теперь её разослать по пользователям (которые видали “ентот ваш мардаун“), или добавить удачно получившуюся инструкцию в нашу Wiki или ещё массу различных вариантов… В общем как теперь из маркдауна сделать другой формат?
Pandoc
Не буду ходить вокруг да около – проблематика ясна, нам нужен конвертор. Конвертор называется pandoc и может работать с командной строки, что не может не радовать. Поддерживает множество различных форматов. В числе которых docx, fb2, mobi (привет электронные книжки), html, wiki (разные варианты), xml, markdown, latex и прочие, прочие, прочие.
Примеры конвертации
Качаем, ставим пандок, запускаем командную строку и переходим в каталог с файлами (ну или кто как привык).
Конвертирование из Markdown в Docx:
pandoc "openvpn.md" -f markdown -t docx -o "openvpn.docx"
По результатам из файла openvpn.md формата [-f = from] markdown будет создан файл [-o = output] openvpn.docx формата [-t = to] docx.
Для конвертирования в DocuWiki, соответственно, укажем -t dokuwiki и всё.
Конвертируется махом.
Как я вижу – документацию делать в markdown с использованием Git. Затем деплоится куда-нибудь на сервер документации, с простой разметкой. И тут либо заранее конвертнуть в docx тот же, или оставить ссылочку на скрип, который на лету это конвертит и присылает в ответ на запрос.
К слову, таким образом попробую себе сделать нормальные fb2 книжки из docx, которые в некоторых случаях почему-то предлагаются для загрузки.
Comments: