Skip to main content

asciidoc: полезные дополнения

Парсер ASCII-art рисунков с сохранением в SVG

Скрипт установки asciitosvg-install.sh:

Использование:

где -s масштаб сетки в пикселях. Хорошо дополняет этот конвертер онлайн-рисовалка ASCIIART’a http://asciiflow.com

(далее…)

читать...

Автовставка истории изменений в техническую документацию на AsciiDoc

Задача

При написании технической документации является хорошим тоном включать секцию с историей изменений (т.н. Revision History). Как правило, сама документация также хранится в гите и имеет свою историю изменений, поэтому грех этим не воспользоваться, чтобы автоматизировать процесс.

Решение

Рассмотрим решение задачи на базе стандарта AsciiDoc, который в последнее время набирает всё большую популярность среди прогрессивно настроенных инженеров и причастных к их результатам деятельности тех.писателей.

Примем, что для истории ревизий нам необходима следующая информация:

  • дата изменения
  • имя автора изменения
  • суть изменения

Для формирования таблицы с историей ревизий используем замечательную команду git log:

— как видим на выходе отличная заготовка для asciidoc-таблицы.

Подробнее об опциях команды:

  • —max-count= — указываем желаемое число последних коммитов
  • —branches= — если интересуют только конкретные ветки (например release/production), указываем тут
  • —tags= — аналогично с тегами, можно задавать паттерн типа rev*.*, v?.?.? и т.п.
  • —no-merges — не выводить в лог слияния веток

У меня установлен гит довольно старый (v1.8), в новых версиях появилась кудо более гибкая кастомизация даты. Тонкую настойку на славянский формат даты «19.2.2015» в новом гите можно осуществить следующей командой:

Также в зависимости от того хранится ли документация отдельно либо является частью репозитария СФ-блока будет различаться git log, возмодно потребуется указывать конкретный исходник документа или группу исходников, например:

или: 

Итоговый скрипт

Получившийся скрипт выглядит следующим образом:

Вызов скрипта: 

В сборочном .adoc-файле включаем сгенерированный файл в соответствующую секцию: 

Также будет полезно добавить revhist.adoc в .gitignore (как файл, генерируемый автоматически); и в мейкфайл — как зависимость при сборке конечного PDF.

 

 

читать...

asciidoctor-pdf: asciidoc для самых маленьких

Для тех кто хотел попробовать подход единого источника при написании технической документации, но кого смущала монстроузность настройки AsciiDoctor‘a (все эти DocBook, xslt, fopub и прочие прелести) есть альтернатива, которая позволит пощупать все прелести аскидока с легким стартом.

Преимущества документации в asciidoc

Для тех, кто забыл или не в теме, напомню основные пункты:

  • Текстовый формат мета-языка разметки (тут же такие wiki-форматы как Markdown, reStructuredText, DokuWiki, etc)
  • Контроль изменений (версионирование в отличие от бинарных форматов документов, позволяющее делать простой diff между ревизиями
  • WYSIWIG-превью в лайв-режиме
  • Возможность накрутки своего корпиративного стиля при генерации различных выходных форматов: pdf, epub,mobi, fb2, html

asciidoctor-pdf

Основное отличие от AsciiDoctor’a  — использование вместо апачевского FO-процессора FOP (java) движка Prawn (Ruby). Также используется значительно облегченная (по сравнению с AsciiDoctor) система конфигов на основе микроразметки YAML.

Установка

Несмотря на то, что asciidoctor-pdf требует наличия ruby >= 2.0.0, по факту его можно установить без ошибок и эксплуатировать лишь на более свежих версиях, к несчастью в CentOS7 установлена 2.0.0:

Чтож, методом проб, ошибок и гугленья устанавливаем 2.3.1:

Ставим зависимости для asciidoctor-pdf:

Ставим сам asciidoctor-pdf:

либо последнюю версию в разработке:

Опционально, для подсветки синтаксиса можно доустановить один из движков на выбор (рекомендуют Rouge как предпочтительный):

Настройка

Конфиг можно иметь по-проектно, либо вынести основные настройки в глобальный конфиг (в нём полезно например хранить настройки шрифтов):

Примеры конфигов для оформления, которые можно использовать как базу  для оформления собственных стилей:

Тестовый запуск примера из репозитория asciidoctor-pdf:

Кириллизация

Шрифты

Из-за подхода к набору символов в шрифтах по умолчанию на кириллических документах вылезает неприятное сообщение:

И кирилические символы не отображаются в выходном документе. Эту проблему можно решить, если подключить внешние шрифты, для этого надо сделать две вещи:

  1. Прописать в конфиг-файле соответствие шрифта и файла, в котором он содержится
  2. При вызове asciidoctor-pdf указать путь к папке, в которой хранятся шрифты (к сожалению, на текущий момент можно передать только один путь)

В конфиге пишем что-то вроде:

Далее указываем где будут использоваться в документе эти шрифты:

Теперь вызываем с указанием, в которой хранятся шрифты (в RHEL/CentOS это, например, /usr/share/fonts):

Метазаголовки

Для корректной локализации различных служебных маркеров, в самом файле документа adoc в самом начале переопределяем переменные (на свой корпоративный вкус):

Дополнительные утилиты

Также в комплекте идёт шелл-скрипт optimize-pdf, который использует Ghostscript для сжатия и минификации выходного pdf.

В системе должен быть установлен Ghostscript >= 9.10, поэтому Cent OS7  в пролете:

 

Ссылки по теме

читать...

[opensource]: генератор распиновки СБИС для оформления даташитов и документации

Постановка задачи

Использование концепции единого источника, минимизация человеческого фактора при одновременной правке табличной информации об изменении/перемещении/исправлении_ошибок в списке внешних ножек СБИС и его графической репрезентации. Притом хорошо бы на выходе получать векторную картинку.

Решение

Исходными данными является (нативная для сборщика документации) таблица в формате asciidoc, которая sed‘ом и grep‘ом переводится в классический CSV (comma separated value), после чего средствами PHP переводим его в JSON, и уже JSON скармливаем скрипту рисования SVG (а если надо — и PNG).

PS: Перевод в JSON — опциональный, просто потому что формат удобный, быть может в будущем в каком-нибудь скрипте прийдётся работать со списком пинов, например, автосоздание либы с символьным обозначением для Altium/PCAD/KiKAD/Eagle.

Возможности

  • Поддержка следующего типа полей из оригинального asciidoc-описания:
    • Номер пина
    • Имя пина
    • Тип пина
    • Стандарт ввода-вывода
    • Описание пина
  • Возможность для любого из полей назначить свой цвет пина (DecidePinColour.php), на данный момент поддерживаются:
    • GND — земля
    • VDD — питание
    • VDDA — питание аналоговых цепей
    • CMOS — цифровые ножки общего назначения
    • LVDS — дифференциальные пары
    • JTAG — отладочные цепи
    • XTAL — тактирующие цепи
    • ANALOG — аналоговые выводы
  • Возможность задания произвольного прямоугольного корпуса — с произвольным соотношением пинов по ортогональным сторонам
  • Возможность опционального задания имени СБИС
  • Возможность задания типа и начертания шрифта для имени СБИС, номера пина, имени пина

(далее…)

читать...