Doka avatar

Журнал Эмбеддед-Инженера

О микроэлектронике, радиотехнике и хобби

Замечательный AsciiDoc

Подсказки по работе с документами в формате AsciiDoc

Dmitry Murzinov

6 минут чтения

Содержание

Вводная информация

Markup Reference

Синтаксис

Линтеры

Блого-движки

..поддерживающие AsciiDoc

Tables

Asciidoctor

asciidoctor --help syntax | asciidoctor -o syntax.html -

i18n

Локализация

Asciidoctor-PDF

Руководство по стилям

Редакторы

Редакторы аскидока с WYSIWIG лайв-превью.

Atom

плагины:

atom.io - пожалуй устаревший редактор, но с подсветкой синтаксиса и лайв-превью. Скачиваем, устанавливаем редактор, устанавливаем плагины:

wget https://atom.io/download/rpm
sudo rpm -Uvh atom.x86\_64.rpm
apm install asciidoc-preview
apm install language-asciidoc
apm install asciidoctor-preview

AsciidocFX

IntelliJ IDEA Community Edition

советы

  1. В корне проекта создай файла .asciidoctorconfig
  2. Добавь в него :imagesdir: .. или :imagesdir: {asciidoctorconfigdir}

KeenWrite

Converters

Преобразования из других форматов

Pandoc

pandoc --list-input-formats
pandoc --list-output-formats

Google Docs -> adoc

Есть плагин для Google Docs: AsciiDoc Processor add-on; подробнее читай тут.

docx -> adoc

TL;DR: pandoc input.docx -f docx -t asciidoctor --wrap=none --markdown-headings=atx --extract-media=extracted-media -o output.adoc

adoc -> docx

Хаки и трюки

Watermark

https://docs.asciidoctor.org/pdf-converter/latest/theme/images/#foreground

Как скрыть заголовок главы/секции

[%notitle]
== Reference Card

Подробнее

Если строчка листинга не влезает без переноса..

..то можно уменьшить (автоматом) размер шрифта конкретного листинга. Используй настройку autofit локально или :autofit-option: глобально. Подробнее.

Контроль переноса заголовка на новую строку

  • Если любой заголовок надо перенести на новую строку в конкретном месте, то используем pass:q[<br>] (:title: при этом для загловка верхнего уровня должно быть закомментировано - поскольку pass:q[<br>] не работает внутри :title:)
  • Если надо в каком-то месте запретить разделять слова при переносе (не только заголовка) на новую строку, то используем {wj}
  • Если надо запретить перенос внутри слова, то используем в таком случае {zwsp} для маркировки мест запретов внутри слова
  • Если по какой-то причине надо больше одного пробела вставить в текст, то используем {nbsp}
  • The word joiner (WJ) is a code point in Unicode that prevents a line break at its position
  • The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary

Названия сущностей и счётчиков

Для рисунков, таблиц, приложений, листингов, примеров.

Block context Caption attribute Counter attribute
appendix appendix-caption appendix-number
example example-caption example-number
image figure-caption figure-number
listing, source listing-caption listing-number
table table-caption table-number

Подсказки по синтаксису

Line breaks preserved using a space followed by the plus sign (+):

Rubies are red, +
Topazes are blue.

rendered as:

Rubies are red,
Topazes are blue.

Line breaks preserved using the hardbreaks option:

[%hardbreaks]
Ruby is red.
Java is beige.

Line breaks preserved throughout the document using the hardbreaks-option attribute:

= Line Break Doc Title
:hardbreaks-option:

Rubies are red,
Topazes are blue.

Как сделать из инклюд-файла список

* {empty}
include::item-text.adoc[]

Для сложных списков:

* {empty}
+
--
include::complex-list-item.adoc[]
--

Инклюд по диапазону строк

include::filename.txt[lines="1..10,15..20"]
include::filename.txt[lines=7;14..25;28..43]
include::filename.txt[lines=12..-1]

Инклюд лишь части файла

В файле который будем инклюдить тегируем нужный франгмент:

# tag::parse[] 
doc = (options[:parse] == timings.record :parse if timings
# end::parse[]

Инклюдим с указанием тэга:

[source,ruby]
----
include::core.rb[tag=parse] 
----

Можно указать несколько тегов: include::core.rb[tags=timings;parse].

NOTE: если это исходник, то для тегирования используем комментарии в соовтетствии с синтаксисом исходника, а если этого аскидок, то используем аскидоковские комментарии: //.

Кастомное задание подписей рисунков, таблиц и блоков

1й вариант:

[caption="FigureZ {chapter-number}.{figure-number}.{counter:figure}. ", reftext="{figure}"]
.principle of work
image::graph.svg[id=graph, width=70%, align=center]

2й вариант:

:figure-caption!:

.Figure {counter:figure-number} Image Caption
image::312.jpg[alt,width=50]

Атрибуты

Типографика

Из полезного:

  • {zwsp} - The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary
  • {wj} - The word joiner (WJ) is a code point in Unicode that prevents a line break at its position

Годные примеры и советы для использования asciidoc на github

Для тех кто предпочитает использовать README.adoc вместо README.md: https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74

Reuse table row across document

A solution with include macro with tag

.table-1
|====
// tag::table-header[]
|this |is |header
// end::table-header[]

.table-2
|====
include::example.adoc[tag=table-header]

Multi-row table headings workaround

две таблицы: красивая и правильная

Исходник таблицы:

[width="100%",cols="^3,18,^7,^6,^6,^6,^5,32",options="header",]
|===
^.^| # ^.^| Parameter ^.^| Name ^.^| Value, min ^.^| Value, typ ^.^| Value, max ^.^| Unit  ^.^| Comment
| 1 | aaa | I | 1 | 2 | 3 | A | Lorem Ipsum
|===

[width="100%",cols="^3,18,^7,^6,^6,^6,^5,32",]
|===
.2+^.^h| # .2+^.^h| Parameter .2+^.^h| Name 3+^.^h| Value         .2+^.^h| Unit .2+^.^h| Comment
                                   ^.^h| min ^.^h| typ ^.^h| max
| 1 | aaa | I | 1 | 2 | 3 | A | Lorem Ipsum
|===

Использовал хак, описанный в этом комменте: он заключается в том, чтобы вручную указывать свойства каждой ячейки. И вроде бы оно работает как надо, только вот почему-то в asciidoctor-pdf стили для options="header" и для присвоения ячейки принудительно свойства хидера h| xyz - различаются, что конечно совсем неудовлетворительно.

Полезные статьи на русском

Источник: https://habr.com/ru/articles/550086/ ; выдержка:

pdf-сравнение версий мы решили сделать с помощью вот этого проекта. Если применить следующее преобразование в ImageMagick, на выходе получаем красивый pdf:

pdf-diff before.pdf after.pdf -t 7 -b 92 | docker run -i dpokidov/imagemagick png:- -crop 294:207 -border 1x% +repage pdf:- > comparison_output.pdf

Всё это не очень хорошо работает на таблицах с заголовками, поскольку повторяющиеся заголовки на каждой странице pdf-diff воспринимает как изменения, если таблица просто сместилась. Также при сравнении альбомных страниц результат получается неудобочитаемым.

Полезные ссылки

Цикл публикаций в блоге про практическое применение аскидока:

Шрифты

Имеющиеся в RPM-дистрибутивах линукса:

sudo yum install -y fontawesome-fonts paratype-pt-sans-caption-fonts paratype-pt-sans-fonts

Последние записи

Разделы