---
description: 'Краткое введение в Asciidoctor'
next: books/fdp-primer/rosetta
params:
  path: /books/fdp-primer/asciidoctor-primer/
prev: books/fdp-primer/doc-build
showBookMenu: 'true'
tags: ["AsciiDoc", "Asciidoctor", "Primer", "Introduction", "Guide"]
title: 'Глава 6. Введение в Asciidoctor'
weight: 7
---

[[asciidoctor-primer]]
= Основы Asciidoctor
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 6
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

Большая часть документации FDP написана с использованием AsciiDoc. В этой главе объясняется, что это значит, как читать и понимать исходный код документации, а также используемые методы. Для получения полного справочника по возможностям Asciidoctor обратитесь к link:https://docs.asciidoctor.org/home/[документации Asciidoctor]. Некоторые примеры, используемые в этой главе, взяты из link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference[краткого справочника по синтаксису AsciiDoc].

[[asciidoctor-primer-overview]]
== Обзор

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

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

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

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

Для удаления [.filename]#/tmp/foo# используйте man:rm[1].

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

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

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

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

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

[[asciidoctor-headings]]
== Заголовки

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

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

....
= Заголовок документа (Уровень 0)

== Заголовок раздела на уровне 1

=== Заголовок раздела на уровне 2

==== Заголовок раздела на уровне 3

===== Заголовок раздела на уровне 4

====== Заголовок раздела на уровне 5

== Другой заголовок раздела на уровне 1
....

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

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

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

== Уровень 1

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

[[asciidoctor-paragraphs]]
== Абзацы

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

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

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

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

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

[[asciidoctor-lists]]
== Списки

Asciidoctor поддерживает несколько типов списков, наиболее распространённые — `ordered` и `unordered`. Для получения дополнительной информации о списках см. link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference].

[[asciidoctor-ordered-lists]]
=== Упорядоченные списки

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

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

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

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

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

[[asciidoctor-unordered-lists]]
=== Неупорядоченные списки

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

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

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

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

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

[[asciidoctor-links]]
== Ссылки

[[asciidoctor-links-external]]
=== Внешние ссылки

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

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

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

[[asciidoctor-links-internal]]
=== Ссылки на другую книгу или статью

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

. Включите файл [.filename]#urls.adoc# из папки [.filename]#~/doc/shared#.
+
....
\include::shared/{lang}/urls.adoc[]
....
+
. Затем создайте ссылку с использованием переменной Asciidoctor на статью `ipsec-must`.
+
....
extref:{ipsec-must}[Статья IPSec-Must]
....
+
И это будет отображено как.
+
extref:{ipsec-must}[Статья IPSec-Must]

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

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

Книги структурированы в разных каталогах для поддержания удобной организации. Чтобы создать ссылку из одного подкаталога книги в другой подкаталог той же книги, используйте макрос `crossref`:
....
crossref:doc-build[documentation-makefile, Эта ссылка]
....
И это будет отображено как

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

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

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

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

[[asciidoctor-images-icons]]
== Изображения и иконки

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

[[asciidoctor-images]]
=== Изображения

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

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

* [.filename]#~/website/static/images/# для веб-сайта.
* [.filename]#~/documentation/static/images/# для документации.

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

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

В качестве примера мы используем заголовок статьи extref:{freebsd-releng}[Подготовка релизов FreeBSD].

[source, asciidoc]
....
= Подготовка релизов FreeBSD
:doctype: article

[...]

:images-path: articles/freebsd-releng/ <1>

[...]

:imagesdir: ../../../images/{images-path} <2>

[...]

....

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

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

Вот пример:

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

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

[[asciidoctor-icons]]
=== Иконки

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

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

....
:icons: font
....

После установки свойства иконки Asciidoctor можно добавить иконку, поддерживаемую link:https://fontawesome.com/v4/icons/[Font Awesome].

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

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

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

[[asciidoctor-conclusion]]
== Заключение

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