Skip to main content

Тех.Документация

Заметки по написанию технической документации согласно концепции единого источника и использованию открытого инструментария для этого: свободные тулы и шрифты, советы, находки

Работа со шрифтами в CentOS 7

Установка шрифтов в CentOS 7

Установка GUI-оболочки над fontconfig’ом (можно будет назначать произвольные шрифты в качестве дефолтных системных):

1
sudo yum install -y fonts-tweak-tool

Установка майкрософтовских шрифтов из репо: 

1
sudo yum install -y msttcore-fonts-installer.noarch

Поиск нужных шрифтов в репо:

1
yum search fonts

Установка сторонних шрифтов

Если  нужных шрифтов нету в репо, их можно добавить в систему сладующим образом:

1. скачать и помесить в папку ~/.fonts/:

1
2
3
wget http://www.paratype.ru/uni/public/PTMonoOFL.zip -O ~/.fonts/PTMonoOFL.zip
cd ~/.fonts
unzip PTMonoOFL.zip

2. дать команду на обновление (пересборку кэша) шрифтов:

1
fc-cache -v

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

1
fc-cache -s

Также полезной будет добавить опцию -f для того чтобы зафорсить перезачитывание каталога шрифтов.

Манипуляции с установленными шрифтами

Вывести списком все установленные шрифты:

1
fc-list

либо только названия установленных шрифтов:

1
fc-list : family

либо только имена файлов (с путями) установленных шрифтов:

1
fc-list : file

либо доступные стили установленных шрифтов:

1
fc-list : style

 

Можно сделать сортировку выведя только доступные шрифты с кириллическим набором символов:

1
fc-list :lang=ru

либо более сложную сортировку:

1
2
$ fc-list :lang=ru | grep -i serif | grep Regular
/usr/share/fonts/google-droid/DroidSerif-Regular.ttf: Droid Serif:style=Regular

 

Также полезным будет просмотр какие шрифты в системе установлены как дефолтные:

1
2
$ fc-match monospace
  DejaVuSansMono.ttf: "DejaVu Sans Mono" "Book"

1
2
$ fc-match regular
  DejaVuSans.ttf: "DejaVu Sans" "Book"

1
2
$ fc-match serif
  DejaVuSerif.ttf: "DejaVu Serif" "Book"

1
2
$ fc-match sans-serif
  DejaVuSans.ttf: "DejaVu Sans" "Book"

Свободные шрифты

Ниже — каталог свободных шрифтов,  которые удалось собрать по крупицам:

Font Awesome (также доступен к установке через yum): https://fortawesome.github.io/Font-Awesome/ (также доступен из репа)

 Кириллические шрифты

Отдельная радость — свободные кириллические шрифты, которые очень прижились при оформлении технической документации в корпоративном стиле. Семейство PT от Paratype — в фаворитах по сей день.

Paratype PT Sans и PT Mono: http://www.paratype.ru/public/

PT Mono Bold: http://www.fontstock.com/public/PTMono.zip

PT Astra Sans и PT Astra Serif: http://astralinux.com/fonts.html

ROSA Arion и ROSA Verde:  http://www.rosatype.ru/

Шрифт «Берёзки» с  кириллическим алфавитом: http://mishapanfilov.ru/font_beryozki.html

Бесплатные кириллические шрифты: http://russianfonts.ru/fonts/gora/goratypeface.html

Ссылки

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Desktop_Migration_and_Administration_Guide/configure-fonts.html

Читать далее

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

(далее…)

Читать далее

asciidoc: введение в концепцию единого источника документации

Установка тулчейна

asciidoctor — лучший способ работы с asciidoc Скачиваем asciidoctor, устанавливаем зависимости и шрифты:

1
2
3
git clone https://github.com/asciidoctor/asciidoctor-fopub.git
sudo yum install -y rubygem-asciidoctor
sudo yum install -y fontawesome-fonts paratype-pt-sans-caption-fonts paratype-pt-sans-fonts

  Также выяснилось, что для корректной работы asciidoctor, из всех установленных версий Java надо выбрать самую последнюю:

1
2
3
rpm -qa | grep openjdk
java-1.8.0-openjdk.x86_64
java-1.7.0-openjdk.x86_64

Это можно реализовать командами:

1
2
sudo update-alternatives --config java
sudo update-alternatives --config javac

 

(далее…)

Читать далее

PDF: советы и шпаргалки

PDFTK

Установка PDFTK в CentOS 7

В CentOS 6 ставилось из коробки:

1
sudo yum install -y pdftk.x86_64

В CentOS 7 же немного поплясять с гуглом, и о счастье — добрый самаритянин сделал неофициальный реп с pdftk:

1
2
3
sudo wget https://copr.fedorainfracloud.org/coprs/robert/gcj/repo/epel-7/robert-gcj-epel-7.repo -P /etc/yum.repos.d
sudo wget https://copr.fedorainfracloud.org/coprs/robert/pdftk/repo/epel-7/robert-pdftk-epel-7.repo -P /etc/yum.repos.d
sudo yum install -y pdftk

Рекомендую еще поставить полезный пакет poppler для манипуляций с PDF: sudo yum install -y poppler-data.noarch poppler.x86_64 poppler-utils.x86_64

Работа с метаданными

Если метаданные содержат кириллицу, то используем команды с суффиксом _utf8! Извлекаем мета-данные:

1
pdftk board-schematic-v4.0.pdf dump_data_utf8 output meta.txt

Редактируем мета-данные:

1
joe meta.txt

Обновляем мета-данные:

1
pdftk board-schematic-v4.0.pdf update_info_utf8 meta.txt output board-schematic-v4.0-meta.pdf

(далее…)

Читать далее