diff options
Diffstat (limited to 'documentation/content/ru/books/fdp-primer/asciidoctor-primer/_index.adoc')
| -rw-r--r-- | documentation/content/ru/books/fdp-primer/asciidoctor-primer/_index.adoc | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/documentation/content/ru/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/ru/books/fdp-primer/asciidoctor-primer/_index.adoc new file mode 100644 index 0000000000..4dc39524fe --- /dev/null +++ b/documentation/content/ru/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -0,0 +1,338 @@ +--- +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 Раздел Заголовок + +====== Level 5 Section Title + +== Другой заголовок раздела первого уровня +.... + +[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]] +== 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> + +ifdef::env-beastie[] +ifdef::backend-html5[] + +[...] + +:imagesdir: ../../../images/{images-path} <2> +endif::[] +endif::[] + +[...] + +.... + +<.> Ссылается на путь внутри папки [.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. Из-за ограничений по объёму и сложности некоторые аспекты не были рассмотрены глубоко (или вообще не затронуты). |