Asciidoctor windows как установить

Обновлено: 04.07.2024

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

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

Глава 2. Обзор технологий

Я начну с краткого обзора технологий, которые применяются для подготовки технической документации. Наиболее известны следующие технологии:

Help&Manual и аналоги;
DocBook;
DITA;
и другие.

Рассмотрим некоторые из этих технологий несколько подробнее.

Глава 3. Help&Manual

Известные минусы H&M и аналогов:

Закрытый бинарный формат файлов; впрочем, это исправляется в новой версии H&M, где используется XML-формат;
Следствие: для просмотра и редактирования нужна сама программа H& M;
Все эти системы платные;
Нет средств для управления версиями документации;
Нет средств для обеспечения одновременной работы нескольких человек над одним документом.

Наш отдел документации, видимо, сравнительно небольшой. Важнее, на самом деле, что над одним документом у нас работает 1-2 человека - писатель и переводчик. Поэтому пока что отсутствие средств для управления версиями нам не слишком мешает.

Глава 4. DocBook

(это полное содержимое файла), то браузер обязан интерпретировать это так же, как код

Сразу видно, что это позволяет значительно упростить разметку. Однако это делает программы для обработки SGML гораздо более сложными и неустойчивыми в работе. До сих пор не существует программ, разбирающих любую разновидность SGML!

Так что сейчас DocBook/SGML не поддерживается, поддерживается только DocBook/XML.

К плюсам этой технологии можно отнести:

Не только открытый, но и стандартный формат, широко используемый как в OpenSource, так и в коммерческих компаниях;
Существующие инструменты позволяют преобразовывать DocBook во все распространённые форматы (HTML, CHM, PDF итп);
За счёт открытости и стандартности возможно реализовать преобразование в любой другой формат;
Формат очень полный; в спецификации предусмотрены, например, специальные теги для сочетаний клавиш, для пунктов меню, и т.п;
Формат можно расширять, дописывая собственные DTD;
Это XML, а для работы с XML существует огромное количество инструментов и технологий;
Т.к. исходные файлы текстовые, их можно держать под управлением системы контроля версий.

К минусам я бы отнёс:

Высокий порог вхождения; нужно знать XML и саму спецификацию DocBook;
Нетривиальная настройка вывода в HTML, PDF и т.п; Например, для вывода в PDF используется либо промежуточный вывод в TeX (так что для настройки нужно знать TeX), либо промежуточный вывод в XSL-FO (так что для настройки нужно знать XSL-FO);
Системы контроля версий не так уж хорошо приспособлены к хранению XML-файлов.

Глава 5. DITA

Некоторыми (особенно в США) формат DocBook рассматривается как устаревающий. На смену ему приходит технология DITA. Это также формат, основанный на XML. Однако базовый формат определяет только основные теги, которые используются в любом документе. Все более специфичные теги определяются в так называемых специализациях DITA с помощью деклараций DTD. Существует несколько стандартных специализаций. Предполагается, что каждый пишет специализацию для своих нужд.

DITA содержит следующие нетривиальные идеи:

БОльшая, даже по сравнению с DocBook, гибкость формата;
И все плюсы DocBook.

По сравнению с DITA Docbook рассматривается как формат для чайников; Как минимум, здесь надо знать не только XML, а ещё и DTD;
Т.к. формат ещё относительно новый, он пока слабее поддерживается;
Тот же минус, что у DocBook: не лучшая поддержка XML со стороны систем контроля версий;
Тот же минус, что у DocBook: сложность настройки вывода в PDF, по тем же причинам.

Про бесплатные WISIWYG-редакторы для DITA я ещё вобще не слышал.

Глава 6. Wiki-подобные разметки

Чтобы не писать в XML, широко используются различные Wiki-подобные разметки. Их очень много. Практически каждый wiki-движок предлагает свой язык разметки. Наиболее известны разметки MediaWiki (используется википедией) и dokuwiki.

Не все wiki-разметки поддерживают все средства форматирования, многие ограничены. Разметка MediaWiki поддерживает практически любое форматирование, но выглядит такая разметка страшновато. Dokuwiki выглядит более читаемо, но не поддерживает некоторое сложное форматирование.

Плюсы такой технологии:

Меньший порог вхождения, чем у XML-технологий;
Системы контроля версий лучше всего работают как раз с plain text файлами;
При использовании DocBook в качестве промежуточного формата получаем все плюсы технологии DocBook;
В принципе, можно использовать DITA вместо DocBook в качестве промежуточного формата;
За счёт наличия конвертеров всегда есть возможность уйти с этой технологии на какую-то другую.

Глава 7. Применение для совместной работы

В основном здесь рассматривается использование web-интерфейса для работы с документами. Однако надо заметить, что это, не единственный вариант. Как минимум не стоит забывать про возможность использования систем контроля версий для совместной работы над документами.

Своеобразная разметка; это тоже wiki-разметка, но уникальная, никто кроме confluence её не поддерживает;
Слабая поддержка импорта: практически есть возможность только импортировать doc-файлы;
Слабая поддержка экспорта: confluence может экспортировать pdf, но так, что этот вариант не многим лучше распечатки веб-страницы на pdf-принтере; другие форматы вывода не поддерживаются;
Сами тексты хранятся в БД, и в случае, если придётся переходить на другую технологию, тексты придётся как-то нетривиально добывать из БД.

Gitit использует для обеспечения совместного редактирования достаточно простую модель. Предположим, один человек (A) начал редактировать страницу, затем (не дожидаясь пока A закончит) её начал редактировать Б. В таком случае, если изменения, внесённые двумя людьми, не пересекаются (например, они редактировали разные части страницы), будут применены все изменения. Иначе тому, кто закончит последним, будет предложено разрешить конфликты вручную.

Системы контроля версий используют примерно ту же модель, но могут обеспечивать бОльшую гибкость: см., например, git merge vs git rebase.

Глава 8. Об импорте и экспорте

Собственно, об экспорте я кратко уже упомянул. Программа pandoc позволяет конвертировать документы в разметке asciidoc в несколько распространённых форматов, включая docbook. В свою очередь, docbook можно сконвертировать во что угодно, даже в xml-формат последней версии H&M.

В случае необходимости можно преобразовать имеющиеся документы в формат asciidoc. В случае с исходными документами в формате H&M используемой, 4й версии, для этого придётся:

Конвертировать исходный hmx файл в xml-формат новой версии H&M, используя конвертер, поставляемый с этой новой версией;
С помощью небольшого скрипта и XSL-таблицы преобразовать полученный набор xml-файлов в один xml-файл docbook;
С помощью ещё одной XSL-таблицы преобразовать docbook в asciidoc.

При этом возникают мелкие недочёты, связанные с особенностями работы H&M. Например, в его xml-файлах встречается разметка вида:

Такая разметка, конечно, превращается в не вполне корректную asciidoc-разметку. Но это, вообще говоря, мелочи, и исправляется "поиском и заменой" в текстовом редакторе.

Глава 9. Улучшение поддержки DocBook

Для обеспечения более полной поддержки DocBook я определил в своём конфигурационном файле Asciidoc дополнительные макросы:

icon:image.jpg[] для вставки иконок;
button:button.jpg[Текст кнопки] для упоминаний кнопок;
label:[Текст] для заголовков элементов управления;
screenshot::screen.jpg[] для больших скриншотов.

Глава 10. Настройка вывода в PDF

Существует несколько способов преобразовать DocBook в PDF. Наиболее распространены два:

С использованием XSL-FO в качестве промежуточного формата;
С использованием LaTeX в качестве промежуточного формата.

Apache FOP (бесплатный, но не поддерживает некоторых возможностей и имеет некоторые сложности с настройкой русскоязычного вывода);
JadeTeX (специальная версия TeX, настроенная так, что понимает xml на входе);
PassiveTeX (что-то из той же серии);
XEP (коммерческий продукт, полностью функциональный, но опять же есть сложности с русским языком).

Собственно, различные сложности с русским языком есть у всех этих вариантов (они всегда решаемы, но это требует времени). Разработка JadeTeX и PassiveTeX, к тому же, на данный момент заморожена.

Сгенерированные dblatex документы используют специальный стиль, поставляемый в комплекте dblatex. Его, конечно, можно модифицировать. XSL-таблицы из комплекта тоже можно настроить под свои задачи.

Глава 11. Вывод в CHM

и в получившемся файле htmlhelp.hhp указать русский язык:

Глава 12. Поддержка составных документов

Таким образом получается подход, близкий к подходу DITA. Текст хранится в отдельных топиках и объединяется согласно картам документов (в формате YAML). При этом получаем даже дополнительную гибкость по сравнению с DITA, т.к. в YAML-карте документа упоминаются не только имена страниц, а и идентификаторы конкретных секций. Благодаря этому можно, например, переставить разделы в выходном документе, не меняя страниц, а меняя только карту документа.

Глава 13. Профилирование

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

DocBook предусматривает атрибуты тегов для профилирования изначально. Их поддержка в asciidoc добавляется редактированием конфигурационного файла. Например, чтобы пометить абзац как относящийся только к ОС Windows, нужно перед абзацем поместить строку [os="windows"] .

Обычно для каждой задачи требуется профилирование сразу по нескольким переменным. Например, у данного заказчика OS Linux, архитектура процессора x86_64, и т.п. Чтобы не указывать каждый раз все параметры вручную, я пишу файл profiles.yaml вида

Здесь каждой цели профилирования сопоставлен набор пар (имя, значение), по которым должно производиться профилирование. Скрипту нужно только указать цель профилирования в качестве аргумента командной строки.

Глава 14. История изменений

Глава 15. Внешние ссылки

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

Эта задача у меня решается следующим образом. Во всех ссылках указываются только идентификаторы целей. При сборке xsl-стили автоматически делают внешними те ссылки, которые ссылаются на идентификаторы, определённые не в собираемом документе. В случае, когда все связанные документы описаны в одном ymap-файле, на этом этапе сборки все документы существуют в виде одного большого xml-документа (правда, он целиком никогда не формируется в виде файла, а только передаётся между скриптами через unix pipes). В такой ситуации не составляет труда с помощью xsl выяснить, какой идентификатор в каком документе определён.

В случаях же, когда некоторые из документов, на которые указывают ссылки из собираемого документа, описаны другими ymap-файлами, эти другие ymap-файлы перечисляются в собираемом ymap-файле в специальном разделе external-documents . Скрипт, преобразующий ymap в xml-документ, читает ymap-файлы, на которые ссылается данный, и в выходном xml-документе формирует тег вида

Таким образом, в xml-документе опять же оказывается определено, какие идентификаторы в каких документах определены, и xsl-стиль может правильно расставить внешние ссылки.

В заголовке использовано слово сложной , под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4 , если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.

Года полтора назад мы втянулись в проект по разработке небольшой отраслевой информационной системы. По этой небольшой системе необходимо было разработать с полсотни взаимоувязанных документов и согласовать их не меньше, чем с сотней человек.

Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc. Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.

Пройдя определённую боль, мы с коллегами решили ей поделиться.

Но сначала о хорошем.

Получилось.
Переиспользование содержания (а его было много) позволило обеспечить согласованность документов. Функции Asciidoc в части переиспользования абсолютно не уступают DITA. Это важно, когда разные документы согласуют более ста специалистов и изменения должны отражаться в большом количестве документов.
Текстовый поиск позволил быстро ориентироваться в массиве исходных текстовых данных.
Условная компиляция включать/не включать данные ДСП (для служебного пользования) позволяет упросить согласование документов в рабочем порядке.
Asciidoc мы активно используем для генерации документации. Например, для генерации отчётных форм внутри решения мы используем тот же Asciidoc. Таким образом, эти отчётные формы мы можем автоматически помещать в документацию. Также прекрасно работает генерация документации на API (REST, SOAP), СУБД, процессы согласования (с помощью PlantUML) и т.п. Автоматически создавать документацию из тестов еще не получилось, но вот здесь получилось, большое спасибо авторам за данную статью.

Так в чём же боль? Их всего две:

внешний вид получаемых печатных форм документов;
процесс согласования.

Сначала о внешнем виде печатных форм документов. Asciidoc поддерживает несколько вариантов генерации печатных документов.

Также нужно отметить, что Asciidoc не поддерживает заголовок таблиц из нескольких строк и стили для ячеек, что в некоторых случаях непреодолимо. Поэтому нам помогли вот с таким проектом (спасибо, Гийом).

Вторая проблема – согласование документов. Согласуем мы не репозиторий, а конкретные документы. И тут выяснилось, что заказчик привык к MS Word для работы с текстовыми документами и знать не хочет о внесении правок в pdf. Более того, все правки заказчик требует в виде изменений в MS Word в режиме рецензирования.

Как-то удалось всё же упросить работать с pdf. А сравнение версий мы решили сделать с помощью вот этого проекта. Если применить следующее преобразование в ImageMagick, на выходе получаем красивый pdf.

Всё это не очень хорошо работает на таблицах с заголовками, поскольку повторяющиеся заголовки на каждой странице pdf-diff воспринимает как изменения, если таблица просто сместилась. Также при сравнении альбомных страниц результат получается неудобочитаемым. И вишенка на торте. После подготовки документов всё равно пришлось вручную переводить некоторые из них в MS Word. Для этого мы конвертировали Asciidoc в html и немного доформатировали. Так себе развлечение.

Файл с расширением ADOC, скорее всего, является файлом AsciiDoc. Короче говоря, эти типы файлов ADOC используются для преобразования простого текстового файла в формат, который легко читается, например, в HTML или PDF.

Однако, в отличие от других языков разметки, файлы ADOC действительно просты в использовании, поскольку они представляют собой просто текстовые файлы, которые могут быть легко прочитаны любым пользователем в их необработанном текстовом виде, даже без понимания языка.

Файлы в формате AsciiDoc обычно не сохраняются в файле с расширением .ADOC, а записываются на языке AsciiDoc, а затем переводятся в HTML, PDF или другой текстовый формат. Вы можете увидеть, как это сделать ниже.

Если ваш файл ADOC не является файлом AsciiDoc, он может быть файлом документа Word с защитой Office Authentica Secure Office.

Файлы ADOC не имеют ничего общего с файлами DDOC или форматами Microsoft Word DOC и DOCX, даже если их расширения совпадают.

Как открыть файл ADOC

Поскольку файлы AsciiDoc представляют собой обычные текстовые файлы, открыть их может любой текстовый редактор. Посмотрите наши любимые в этом списке лучших бесплатных текстовых редакторов, но другие также работают, как приложение Notepad, встроенное в Windows.

Поскольку большинство текстовых редакторов, вероятно, не распознают файлы с расширением .ADOC, вам сначала нужно открыть текстовый редактор, а затем открыть файл ADOC через меню open программы.

Файлы ADOC обычно используют специальный синтаксис, такой как двоеточия, точки и скобки, чтобы процессор AsciiDoc мог отображать простой текст в формате, который легко читается. Вы можете узнать больше об этом в Кратком справочнике AsciiDoc по синтаксису Asciidoctor.

Файлы ADOC, являющиеся файлами документов Authentica Secure Office Protected Word, можно открыть с помощью веб-службы Signa.

У вас может быть программа на вашем ПК, которая пытается открыть файл ADOC, когда вы дважды щелкаете по нему или дважды щелкаете по нему. Если это так, и вы хотите это изменить, см. Руководство по изменению программы по умолчанию для определенного расширения файла, чтобы заставить Windows использовать другую программу для открытия файла ADOC.

Как конвертировать файл ADOC

Вы можете перевести файл AsciiDoc в HTML, PDF, EPUB и другие форматы, используя процессор Asciidoctor. См. Как я могу сделать документ? руководство на сайте Asciidoctor, чтобы узнать, как. Однако, прежде чем вы сможете это сделать, вы должны установить Asciidoctor.

Нам неизвестно о каких-либо конвертерах файлов, которые могут преобразовать файл документа Word с защитой Office Authentica Secure Office в другой формат.

Все еще не можете открыть файл?

Важно убедиться, что, если вы не можете открыть свой файл с помощью ножей или конвертеров ADOC, вы действительно имеете дело с файлом ADOC. Легко спутать другой формат с этим, потому что некоторые расширения файлов выглядят очень похоже.

В качестве примера рассмотрим файлы ADO. Они выглядят как файлы ADOC, но на самом деле это файлы параметров Adobe Photoshop Duotone, которые можно открыть только в Adobe Photoshop. Другой формат документа ActivDox, который использует расширение файла ADOX.

Однако помните, что даже после того, как вы попробуете все это, все еще возможно, что формат файла ADOC слишком неясен. Программное обеспечение может быть доступно только с установочного компакт-диска устройства, например, но не онлайн.

В этой статье хочу рассмотреть возможности Asciidoc в части обеспечения требований соответствия документов требованиям единой системы конструкторской документации (ЕСКД), конкретно ГОСТ Р 2.105—9 (далее ГОСТ ЕСКД). Почему именно Asciidoc, я писал здесь.

Сразу уточню. Вопрос форматирования документа здесь не рассматривается. Создающий документацию не должен задумываться о форматировании. Как системный аналитик я создаю содержание и контролирую его структуру. Для получения документа, соответствующего ГОСТ ЕСКД или другому аналогичному стандарту, я должен нажать кнопку и получить корректно отформатированный документ в любых требуемых вариантах: pdf, Open Document (Libre
Office/Open Office), Open XML (Microsoft Word) и прочих.

Рассмотрим структуру документа Asciidoc, соответствующего требованиям
ГОСТ ЕСКД.

В пункте 6.1.1 ГОСТ ЕСКД приведена рекомендуемая структура, которую в Asciidoc можно отобразить следующим образом.

Обратите внимание: здесь нет раздела «титульный лист», он определяется настройками форматирования. В титульном листе, как минимум, должно присутствовать наименование документа, а также другие атрибуты: автор, место выпуска, год выпуска и т.п. Эти атрибуты задаются прямо в документе.

Здесь и далее для обозначения идентификаторов используется транслитерация, ГОСТ 7.79-2000 (система Б). Разработчики данного ГОСТ совершили лёгкое вредительство, не позволяющее использовать его для идентификаторов, поэтому мы используем доработанную версию, подробности здесь.

Для некоторых атрибутов предусмотрен упрощенный синтаксис, в данном случае наименование документа вводится первой строкой после одного знака = .

Раздел с содержанием (подраздел 6.2 ГОСТ ЕСКД) заполняется автоматически при генерации документации.

Разделы «Приложение» (подраздел 6.3 ГОСТ ЕСКД), «Библиография» (подраздел 6.4. ГОСТ ЕСКД) и «Предисловие» определены специальными ключевыми словами:

preface даст возможность процессору Asciidoctor понять, что не
нужно включать этот раздел в содержание;

appendix позволит автоматически нумеровать приложения буквами;

bibliography объявляет раздел с библиографическими ссылками
документа.

Список литературы задаём в файле формата BibTeX.

В самом документе необходимо использовать следующий синтаксис.

Требования к делению документов на части определены в подразделе 6.5 ГОСТ ЕСКД. Для деления документа на разделы/подразделы/пункты используется синтаксис:

Атрибут secnums задаёт нумерацию разделов полностью по ГОСТ ЕСКД.

Чтобы Asciidoc отличал пункт от заголовка раздела (особенно, если пункт не имеет заголовка) можно использовать специальную роль, например [.punkt]. Роль задаём над заголовком.

Требования к перечислениям определены в подразделе 6.7 ГОСТ ЕСКД. В Asciidoc перечисления задаются так:

Обратите внимание: у перечисления может быть наименование. В ГОСТ ЕСКД такого понятия нет, но Asciidoc позволяет в печатном документе не отрывать наименование от перечисления. В некоторых случаях это можно использовать.

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

В ГОСТ ЕСКД возможно маркировать первый уровень перечислений дефисом. Для этого приведённый пример переоформим следующим образом.

Asciidoc допускает вложенность пунктов до пятого уровня.

В качестве примера рассмотрим таблицу, приведённую на рисунке 1 ГОСТ ЕСКД (пункт 6.8.1).

Результат зависит от настроек форматирования. Заданная выше таблица будет выглядеть приблизительно следующим образом.

Наименование таблицы, как и наименование любых других элементов, вводим через символ «точка». Номер таблицы должен проставляться автоматически в соответствии с правилами форматирования.

В атрибуте cols ( cols = "2,1,1,1,1" ) указано, что в таблице будет 5 колонок, причём первая будет в два раза больше остальных.

В атрибуте hrows указано количество строк в шапке таблицы. Шапка в соответствии с требованиями ГОСТ ЕСКД отображается на каждой странице, если таблица занимает более одной страницы.

В ГОСТ ЕСКД есть требование помещать слова «Продолжение таблицы» с указанием номера (обозначения) таблицы в начале каждой странице, на которую переносится таблица. Однако пункт 6.8.7 ГОСТ ЕСКД разрешает не указывать эту надпись при подготовке документа с использованием программных средств.

В самой таблице каждая ячейка начинается с вертикальной черты ( | ). Обычно между строками таблицы делают дополнительный перенос строки, так с таблицей легче работать.

Первая ячейка таблицы занимает по вертикали место двух ячеек, поэтому использован синтаксис .2+\| . Заголовки граф занимают две ячейки по горизонтали, использован аналогичный синтаксис, но без точки: 2+\| .

Для размещения графического материала (подраздел 6.9 ГОСТ ЕСКД) используем следующий синтаксис:

Нумерация рисунков, как и в случае с таблицами делается автоматически.

Если изображение расположено внутри текста, то вместо двух двоеточий необходимо указать одно.

Атрибуты изображения необходимы, чтобы указать, как картинка должна отображаться в документе. Можно воспользоваться имеющимися атрибутами или реализовать свои.

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

Когда я писал конвертер в Open Document, то решил это добавлением специальных свойств, контролирующих оптимальное расположение. В общем случае проблему придётся решать для каждого выходного формата. Правда, всего один раз. В отличие от использования MS Word, где подгонка каждой картинки лежит на плечах пользователя.

Для процессора Asciidoctor реализовано расширение Asciidoctor Diagram для внедрения непосредственно в текст диаграмм, графиков и других элементов.

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

Результат должен выглядеть следующим образом:

Оформляют такие диаграммы также, как обычные изображения.

Работа с формулами (подраздел 6.10 ГОСТ ЕСКД) аналогична работе с диаграммами: формулы можно задать прямо в тексте. В следующем примере формула задана на языке LaTeX/Mathematics:

Часто формулы имеют пояснения. Чтобы указать Asciidoc, что абзац является именно пояснением к формуле, необходимо присвоить ему какую-то роль, например.

Ключевое слово stem означает, что формула помещена внутри текстовой строки.

Обратите внимание на символ + в конце строки. Он означает перенос текста на другую строку без завершения абзаца.

Аналогично реализуются другие элементы с фиксированным форматированием: примечания, примеры и т.п. Роль можно присваивать как отдельному абзацу, так и более крупному фрагменту текста.

Ссылки (подраздел 6.11 ГОСТ ЕСКД) в Asciidoc реализованы так: каждому объекту, на который необходима ссылка, присваивают идентификатор. Например, идентификатор для картинки может быть задан в удвоенных парных квадратных скобках:

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

В этом случае текст в документе будет выглядеть так:

Для html-варианта (например, в интерактивной справке) можно вместо текста \"рисунок 1\" отображать его название.

Не очень красивым выглядит то, что в тексте документа слово \"рисунок\" повторяется дважды. Но это самый простой вариант, который позволяет с одной стороны соответствовать ГОСТ ЕСКД, а с другой — сохранять падежи при использовании автоматизированной генерации документов.

Для сносок (подраздел 6.13 ГОСТ ЕСКД) в Asciidoc существует специальный синтаксис.

f1 в данном случае — идентификатор сноски, если необходимо поместить её более, чем в одном месте.

Asciidoc позволяет создавать документацию в соответствии с требованиями ЕСКД.

Синтаксис Asciidoc не сложнее самого ГОСТ Р 2.105—9.

Можно забыть о стилях MS Word и сконцентрироваться на содержании
создаваемых документов.

Читайте также: