Глава 6. Введение в Asciidoctor

Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.

Содержание

Большая часть документации FDP написана с использованием AsciiDoc. В этой главе объясняется, что это значит, как читать и понимать исходный код документации, а также используемые методы. Для получения полного справочника по возможностям Asciidoctor обратитесь к документации Asciidoctor. Некоторые примеры, используемые в этой главе, взяты из краткого справочника по синтаксису AsciiDoc.

6.1. Обзор

В первые дни существования компьютеров электронный текст был простым. Существовало несколько наборов символов, таких как ASCII или EBCDIC, но на этом всё и заканчивалось. Текст был текстом, и вы видели именно то, что получали. Никаких изысков, никакого форматирования, никакого интеллекта.

Неизбежно, этого оказалось недостаточно. Когда текст представлен в формате, пригодном для машинной обработки, ожидается, что машины смогут использовать и обрабатывать его интеллектуально. Авторы хотят указывать, что определённые фразы должны быть выделены, добавлены в глоссарий или преобразованы в гиперссылки. Имена файлов могут отображаться моноширинным шрифтом при просмотре на экране, но курсивом при печати или в любом другом из множества вариантов представления.

Однажды надеялись, что искусственный интеллект (ИИ) сделает это легко. Компьютер прочитает документ и автоматически определит ключевые фразы, имена файлов, текст, который читатель должен ввести, примеры и многое другое. К сожалению, в реальной жизни всё оказалось не так просто, и компьютерам до сих пор требуется помощь, прежде чем они смогут осмысленно обрабатывать текст.

Точнее говоря, им нужна помощь в определении, что есть что. Рассмотрим этот текст:

Для удаления /tmp/foo используйте rm(1).

% rm /tmp/foo

Читателю легко понять, какие части являются именами файлов, какие — командами для ввода, какие — ссылками на страницы руководства и так далее. Однако компьютер, обрабатывающий документ, не может надежно определить это. Для этого нам нужна разметка.

Предыдущий пример фактически представлен в этом документе следующим образом:

To remove */tmp/foo*, use man:rm[1].

[source,shell]
----
% rm /tmp/foo
----

6.2. Заголовки

Asciidoctor поддерживает шесть уровней заголовков. Если тип документа article, можно использовать только один заголовок уровня 0 (=). Если тип документа book, то может быть несколько заголовков уровня 0 (=).

Вот пример заголовков в article.

= Название документа (Уровень 0)

== Уровень 1 Название Раздела

=== Уровень 2 Раздел Заголовок

==== Уровень 3 Раздел Заголовок

===== Уровень 4 Раздел Заголовок

====== Level 5 Section Title

== Другой заголовок раздела первого уровня

Уровни разделов нельзя пропускать при вложении разделов.

Следующий синтаксис неверен.

= Заголовок документа

== Уровень 1

==== Уровень 3

6.3. Абзацы

Абзацы не требуют специальной разметки в AsciiDoc. Абзац определяется одной или несколькими последовательными строками текста. Чтобы создать новый абзац, оставьте одну пустую строку.

Например, это заголовок с двумя абзацами.

= Это заголовок

Это первый абзац. Это тоже первый абзац.

А это второй абзац.

6.4. Списки

Asciidoctor поддерживает несколько типов списков, наиболее распространённые — ordered и unordered. Для получения дополнительной информации о списках см. AsciiDoc Syntax Quick Reference.

6.4.1. Упорядоченные списки

Для создания нумерованного списка используйте символ ..

Например, это нумерованный список.

. Первый пункт
. Второй пункт
.. Подпункт второго пункта
. Третий пункт

И это будет отображено как.

  1. Первый пункт

  2. Второй пункт

    1. Подпункт второго пункта

  3. Третий пункт

6.4.2. Неупорядоченные списки

Для создания маркированного списка используйте символ *.

Например, это ненумерованный список.

* Первый пункт
* Второй пункт
** Подпункт второго пункта
* Третий пункт

И это будет отображено как.

  • Первый пункт

  • Второй пункт

    • Подпункт второго пункта

  • Третий пункт

Чтобы указать на другой веб-сайт, следует использовать макрос link.

link:https://www.FreeBSD.org[FreeBSD]

Как описано в документации Asciidoctor, макрос link не требуется, когда цель начинается со схемы URL, такой как https. Тем не менее, рекомендуется всё равно использовать его, чтобы гарантировать корректное отображение ссылки в Asciidoctor, особенно в языках с нелатинской письменностью, таких как японский.

Для указания на другую книгу или статью следует использовать переменные Asciidoctor. Например, если мы находимся в статье cups и хотим сослаться на ipsec-must, необходимо выполнить следующие шаги.

  1. Включите файл urls.adoc из папки ~/doc/shared.

    include::shared/{lang}/urls.adoc[]

  2. Затем создайте ссылку с использованием переменной Asciidoctor на статью ipsec-must.

    extref:{ipsec-must}[Статья IPSec-Must]

    И это будет отображено как.

    Статья IPSec-Must

Макрос extref определён как расширение. Он предназначен для корректного отображения ссылки в различных выходных форматах

6.5.3. Ссылки на тот же файл или на другой файл в той же книге

Книги структурированы в разных каталогах для поддержания удобной организации. Чтобы создать ссылку из одного подкаталога книги в другой подкаталог той же книги, используйте макрос crossref:

crossref:doc-build[documentation-makefile, Эта ссылка]

И это будет отображено как

Эта ссылка

Макрос crossref определен как расширение. Он предназначен для формирования корректной ссылки в различных выходных форматах

Используйте макрос crossref для внутридокументных ссылок. Хотя указание имени текущего документа может быть неудобным, это гарантирует корректное отображение ссылки в различных выходных форматах

Не используйте макрос xref или его сокращение << >>. Они не работают хорошо во всех выходных форматах.

6.6. Изображения и иконки

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

6.6.1. Изображения

Изображения помогают проиллюстрировать сложные концепции, делая их более понятными для пользователей.

Первым шагом будет добавление изображения в директорию images по пути:

  • ~/website/static/images/ для веб-сайта.

  • ~/documentation/static/images/ для документации.

Например, чтобы добавить новое изображение в процесс установки FreeBSD, изображение сохраняется по пути ~/documentation/static/images/books/handbook/bsdinstall/new-image3.png.

Следующим шагом будет настройка атрибутов Asciidoctor images-path и imagesdir.

В качестве примера мы используем заголовок статьи Подготовка релизов FreeBSD.

= Подготовка релизов FreeBSD
:doctype: article

[...]

:images-path: articles/freebsd-releng/ (1)


[...]

:imagesdir: ../../../images/{images-path} (2)

[...]
1Ссылается на путь внутри папки /static/images.
2Делает ссылку на атрибут Asciidoctor.

Как только изображение окажется в нужном пути и атрибуты Asciidoctor будут настроены в документе, можно использовать макрос image.

Вот пример:

image::new-image3.png[New step in the FreeBSD install process]

Для улучшения доступности обязательно добавлять описательный текст к каждому изображению.

6.6.2. Иконки

Значки служат интуитивно понятными символами для быстрого распознавания и навигации.

Первым шагом для использования иконок является добавление свойства icons в раздел свойств Asciidoctor в начале каждого документа.

:icons: font

После установки свойства иконки Asciidoctor можно добавить иконку, поддерживаемую Font Awesome.

Это пример использования иконки envelope:

icon:envelope[link=mailto:test@example.com, title="contact"]

Для повышения доступности веб-сайта атрибут title является обязательным.

6.7. Заключение

Это заключение введения в Asciidoctor. Из-за ограничений по объёму и сложности некоторые аспекты не были рассмотрены глубоко (или вообще не затронуты).

Изменено: 25 сентября 2025 г. by Fernando Apesteguía

Главная