В поисках редактора Github-flavored Markdown

Обоснование

Я занимаюсь преподаванием в техническом ВУЗе. И для меня это не основная работа — прежде всего я инженер-программист. Как инженер, я стараюсь всё автоматизировать. Чтобы не повторяться на лекциях и практиках раз за разом, я пишу примеры и статьи для своих курсов.

Есть ряд требований к формату моих примеров:

• Примеры кода должны иметь читаемый, прокомментированный в нужных местах код, понятный даже новичку в предметной области курса
• Но даже читаемого кода недостаточно: на каждый пример нужна статья-путеводитель
• В этой статье будет отполированный текст, схемы, иллюстрации и примеры кода.
• Стиль должен накладываться на уже готовый контент.

На один курс требуется порядка 10-30 объёмных статей. Верстать такие статьи в MS Word или LibreOffice Writer — удовольствие так себе, потому что станет трудно отделять контент от стилей, вставлять куски кода или обеспечивать удобную навигацию по серии статей.

В конце концов я пришёл к Github-flavored Markdown. Работа с онлайн-редакторами Markdown быстро обескураживает, и встаёт вопрос выбора Offline-редактора.

ReText на Ubuntu

На Ubuntu после прочтения ряда отзывов я выбрал редактор ReText — открытое ПО, которое разрабатывается в репозитории на github.

Об этом редакторе есть хорошая статья на хабре: habrahabr.ru/post/161669

Несомненные плюсы редактора:

• Парсер редактора хорошо умеет работать в Github-совместимом режиме, и это большая редкость среди редакторов Markdown
• Есть live preview, который включается в меню редактора
• Есть публикация в ODT и PDF
• Есть поддержка расширений, которая позволяет включить подсветку кусков исходного кода в Preview документа, включить Table of Contents и другие подобные вещи. В сочетании с публикацией в PDF/ODT это часто работает неправильно.
• На заметку: я для себя перечислял через запятую расширения "codehilite" и "toc", которые после перезапуска редактора начинали работать.

Минусы:

• В сочетании с публикацией в PDF/ODT расширения часто работают неправильно.
• Live preview пока что посредственно работает с автоскроллингом: если вы редактируете текст, автоскроллинг preview может уйти куда-либо в сторону на сложных документах.
• Публикация в ODT реализована простым созданием объекта класса QTextDocument и записью его с помощью QTextDocumentWriter. В результате корректно генерируются только простые документы, а в сложных стили, подсветка кода или Table of Contents могут слететь, и даже простые маркеры списков экспортируются неправильно.

Пользователям Linux я бы посоветовал поставить версию из репозитория Github, а не из системных репозиториев. В этом случае вы встретите меньшее число недоработок.
 
   

Github Atom на любой платформе

Другой удобный вариант — это Github Atom, который обладает всеми плюсами предыдущего редактора (кроме разве что экспорта в ODT). Кроме того, Github Atom легко устанавливается на любой платформе, и имеет средства, например, для просмотра файловой структуры.

Несколько советов:

• Если вы набираете русский текст, то отключите в настройках встроенный плагин Spell Check. На момент написания этого поста плагин ищет ошибки только по английскому словарю, и безнадёжно подчёркивает красным цветом весь русскоязычный текст.
• В основной поставке атома уже есть поддержка Preview: хоткей "Ctrl+Shift+M"
• Есть сторонний пакет "markdown-scroll-sync", который качественно синхронизирует курсор в тексте и прокрутку preview документа
• Встроенный парсер Markdown может запросто сломаться на вставках исходного кода. Пакет "language-markdown" перегружает и улучшает встроенный парсер, исправляя его от поломок и добавляя подсветку вставок исходного кода.

Публикация на Github Pages

Сервис Github предоставляет хостинг статических сайтов, известный как Github Pages. Никакого бекенда — всё должно быть на Javascript (без XHR, т.е. без запросов на другие доменты), CSS и HTML. Правда, есть интеграция с генератором Jekyll, который превращает Markdown в HTML, а SCSS в CSS.

Если вы хотите развернуть свой сайт со статьями на Markdown, дам несколько советов:

• Jekyll написан на Ruby, и его проще развернуть на Linux или MacOSX, а не на Windows. Однако, знание Ruby вам едва ли потребуется.
• Будьте готовы испортить свой Markdown из-за заголовка, который вам придётся добавлять в каждую статью. В примере ниже свойство title можно и не ставить, а вот разделители "---" поставить придётся в любом случае, иначе Jekyll просто не будет обрабатывать весь файл:

---
title: 'UV-параметризация сферы'
---

• Чтобы запустить локальную версию сайта на http://localhost:4000/, запустите Jekyll в режиме веб-сервера командой "jekyll serve". Jekyll будет автоматически отслеживать изменения в каталоге проекта и перегенерировать файлы.
• Если вы хотите, чтобы ваши статьи имели обозначенный вами же preview в соцсетях, вы можете настроить интеграцию OpenGraph с Jekyll.

Исходники моего собственного сайта лежат в репозитории ps-group/ps-group.github.io. Вы можете изучить его как неидеальный, но вполне практичный пример настройки Jekyll.

На сегодня у меня всё.

Маленькие заметки о Chroot

Я хочу получить свой маленький билд-сервер под Ubuntu. Билд-сервер должен быть локальным, вложенным в основную систему, и при этом должен полностью изолировать исходники от живущих снаружи компиляторов, библиотек и прочего барахла (своего рода SDK своими руками).

Здесь будут полезные заметки, которые появились в ходе попыток это сделать.

На билдсервере должна быть минимальная система для динамической линковки:

• GLibc, а лучше LSB libc (минимальная POSIX-совместимая библиотека C, предоставленная проектом Linux Standards Base)
• Библиотеки криптографии (т.к. они иногда обновляются с целью закрытия уязвимостей).
• Библиотеки мультимедиа: OpenGL, OpenAL, SDL2, SDL1.2 (т.к. они соединяют с драйверами)
• Возможно, ещё какие-то библиотеки, которые имеют стабильные API и ABI

Всё остальное должно быть доступно лишь для статической линковки:

• C++ STL (варианты: libstdc++, libc++)
• C++ Boost
• C++ Cocos2dx
• C++ Cinder
• C++ SFML
• C GLFW
• И так далее

Chroot и Debootstrap

ОС Linux позволяет создать виртуальную корневую директорию, и войти в неё из-под оболочки терминала. Получается система в системе, причём вложенная система изолирована (не от вредоносного ПО, а от случайного обращения наружу).

Скрипт debootstrap есть в репозиториях Ubuntu, он позволяет скачать и установить в виртуальный корень целый дистрибутив Debian или Ubuntu произвольной версии. После установки можно будет сделать chroot во вложенную систему, и уже там установить необходимое окружение разработки и так далее.

Вот две типичных команды скачивания/установки вложенной системы

# Скачает и установит 32-битной Trusty (Trusty - это Ubunty 14.04) в папку ./trusty32
sudo debootstrap --arch i386 trusty ./trusty32/
# Скачает и установит Trusty родной архитектуры (x64 на моей машине) в папку ./trusty64
sudo debootstrap trusty ./trusty64/

Ещё debootstap позволяет

• Поставить систему неродной архитектуры, пусть даже ARM (тогда будет запускаться через QEMU)
• Поставить любую доступную версию Debian или Ubuntu
• Указать зеркало, с которого скачивать пакеты (например, зеркала Yandex или локальный сервер в Вашей организации)

Настройка chroot после установки вложенной ОС

1. Чтобы войти в chroot-папку, введите "sudo chroot ./trusty32" (trusty32 - путь к вложенной системе в моём случае)
2. После установки локаль ещё не настроена, что делает систему не совсем работоспособной. Нагугленная настройка в две строчки выручила меня:

   # Английский язык (Американский диалект), кодировка UTF-8.
   echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
   locale-gen

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

   # Выполнить 1 раз и пройти консольный мастер настройки пользователя "bb"
   adduser bb
   # Выполнять каждый раз для логина под пользователем bb
   su - bb

4. ...

Пост будет обновляться.