Skip to main content

asciidoc

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/bin/bash
sudo yum install mercurial git gcc php
 
git clone https://github.com/dhobsd/asciitosvg.git
hg  clone https://bitbucket.org/wez/jlexphp
hg  clone https://bitbucket.org/wez/lemon-php
 
cd jlexphp
javac -Xlint JLexPHP/Main.java
jar cvf JLexPHP.jar JLexPHP/*.class
cd ..
 
cd lemon-php
cc -o lemon lemon.c
cd ..
 
cd asciitosvg
make

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

1
a2s -i<исходник.ascii> -o<вых.картинка.svg> [-sx-scale,y-scale]

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

(далее…)

Читать далее

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

Задача

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

Решение

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
$ git log --max-count=10 --no-merges --date=short --pretty=format:"| %ad | %an | %s"
| 2017-04-05 | Dmitry Murzinov | [ipxact2verilog] minor changes
| 2017-04-04 | Dmitry Murzinov | minor changes
| 2017-04-04 | Dmitry Murzinov | First scatch for verilog CSR generator
| 2017-04-03 | Dmitry Murzinov | Was added Make to build translate files (*.mo) for gettext
| 2017-04-03 | Dmitry Murzinov | Was added multilingual support to AsciiDoc Register Overview table
| 2017-04-03 | Dmitry Murzinov | First try to multilingual support
| 2017-04-03 | Dmitry Murzinov | an AsciiDoc Register Overview table now data width independent
| 2017-04-03 | Dmitry Murzinov | Was added dimension of fields for Regs Overview table
| 2017-04-03 | Dmitry Murzinov | Ability to generate an AsciiDoc Register Overview table
| 2017-04-03 | Dmitry Murzinov | Was added an example config file

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

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

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

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

1
git log -n 10 --date=format:'%d.%m.%Y' --pretty=format:"| %cd | %cn | %s" 

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

1
git log -n 10 --pretty=format:"| %ad | %an | %s"  doc/src/IP-core.adoc

или: 

1
git log -n 10 --pretty=format:"| %ad | %an | %s"  doc/src/*.adoc

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

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

1
2
3
4
5
6
7
#!/bin/bash
echo ".Revision History" > $1
echo "[cols=\"^2s,^8,^26\",options=\"header\"]" >> $1
echo "|===================================================" >> $1
echo "| Date | Author | Comments" >> $1
git log --max-count=10 --date=short --pretty=format:"| %ad | %an | %s" doc/src/*.adoc >> $1
echo "|===================================================" >> $1

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

1
./generate-revision-history.sh revhist.adoc

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

1
2
3
4
5
[abstract]
== История изменений документа / Revision Changes
 
include::revhist.adoc[leveloffset=+1]
<<<<

Также будет полезно добавить 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:

1
2
$ ruby --version
ruby 2.0.0p598 (2014-11-13) [x86_64-linux]

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

1
2
3
4
5
6
7
8
curl -sSL https://rvm.io/mpapis.asc | sudo gpg --import -
curl -L get.rvm.io | sudo bash -s stable
source /etc/profile.d/rvm.sh
rvm reload
rvm requirements run
rvm install 2.3.1
rvm use 2.3.1 --default
ruby --version

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

1
2
3
4
5
6
7
8
9
10
$ gem install prawn --version 1.3.0
$ gem install addressable --version 2.4.0
$ gem install prawn-svg --version 0.21.0
$ gem install prawn-templates --version 0.0.3
$ gem install prawn-table --version 0.2.2
$ gem install prawn-icon --version 1.3.0
$ gem install treetop
$ gem install thread_safe
$ gem install safe_yaml
$ gem install asciidoctor

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

1
$ gem install asciidoctor-pdf --pre

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

1
2
git clone --depth=1 https://github.com/asciidoctor/asciidoctor-pdf
cd asciidoctor-pdf/bin

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

1
2
3
$ gem install rouge
$ gem install pygments.rb
$ gem install coderay

Настройка

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

1
gems/asciidoctor-pdf-v.v.v/data/themes/default-theme.yml

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

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

1
asciidoctor-pdf -a pdf-style=../data/themes/base-theme.yml ../examples/basic-example.adoc

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

Шрифты

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

1
The following text could not be fully converted to the Windows-1252 character set: ...

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
font:
  catalog:
    Consolas:
      normal: consola.ttf
      bold:   consolab.ttf
      italic: consolai.ttf
      bold_italic: consolaz.ttf
    Verdana:
      normal: verdana.ttf
      bold:   verdanab.ttf
      italic: verdanai.ttf
      bold_italic: verdanaz.ttf

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

1
2
3
4
5
base_font_family: Verdana
...
literal_font_family: Consolas
...
code_font_family: Consolas

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

1
asciidoctor-pdf -a pdf-style=theme.yml -a pdf-fontsdir=/usr/share/fonts/msttcore example.adoc

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

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

1
2
3
4
:listing-caption: Код
:chapter-label: Глава
:toc-title: Оглавление
:version-label: Версия

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

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

1
$ ./optimize-pdf basic-example.pdf

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

1
2
$ gs -v
GPL Ghostscript 9.07 (2013-02-14)

 

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

Читать далее

[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 — аналоговые выводы
  • Возможность задания произвольного прямоугольного корпуса — с произвольным соотношением пинов по ортогональным сторонам
  • Возможность опционального задания имени СБИС
  • Возможность задания типа и начертания шрифта для имени СБИС, номера пина, имени пина

(далее…)

Читать далее