--- 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. Из-за ограничений по объёму и сложности некоторые аспекты не были рассмотрены глубоко (или вообще не затронуты).