Path: blob/main/documentation/content/ru/books/fdp-primer/asciidoctor-primer/_index.adoc
18099 views
---
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:[email protected], title="contact"]
....
[TIP]
====
Для повышения доступности веб-сайта атрибут `title` является обязательным.
====
[[asciidoctor-conclusion]]
== Заключение
Это заключение введения в Asciidoctor. Из-за ограничений по объёму и сложности некоторые аспекты не были рассмотрены глубоко (или вообще не затронуты).