Автоматическая генерация технической документации / хабр

Файловая (физическая) структура документа

Документ можно легко разделить на несколько файлов, с использованием объектов-подстановок (entities) следующим очевидным образом:

  <!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" >
 
  <book id="lib-book-tech" lang="ru"><title>Технологии разработки</title>
    &intro.sgm;           <!-- О документе -->
    &sgml.sgm;            <!-- Ведение документации -->
    &db.sgm;              <!-- Описание информационной модели -->
    &lib-sql.sgm;         <!-- Разработка серверной части -->
    &lib-tools.sgm;       <!-- Дополнительные средства -->
  </book>

Обратите внимание, что включаемые файлы, содержащие части документа, не должны содержать никаких заголовков или деклараций — файл intro.sgm:

 <preface ID="intro" revision="$Date: 2001/12/27 14:25:13 $">
   <title>Структура документа</title>
   <abstract><para>Данная книга содержит информацию 
         о применяемых технологиях разработки проектов и
         предназначена для использования в качестве справочника по ним.</para>
   </abstract>
 </preface>

Можно отделить и автоматизировать процесс декларации Docbook-файлов в виде entities, например написав скрипт, который для всего каталога генерирует файл !filelist (рекурсивно включающий файлы !filelist из подкаталогов):

  <!ENTITY % subdirectory1.fl SYSTEM "subdirectory1\!file-list">
  %subdirectory1.fl;
  <!ENTITY % subdirectory2.fl SYSTEM "subdirectory2\!file-list">
  %subdirectory2.fl;
  <!ENTITY intro.sgm     SYSTEM "intro.sgm">
  <!ENTITY sgml.sgm      SYSTEM  "sgml.sgm">
  <!ENTITY db.sgm        SYSTEM "db.sgm">
  <!ENTITY lib-sql.sgm   SYSTEM "lib-sql.sgm">
  <!ENTITY lib-tools.sgm SYSTEM "lib-tools.sgm">

Сам документ при этом становиться неизменным, и в нем, с помощью entities можно включать все файлы из каталога документа и его подкаталогов:

  <!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" >
 
  <book id="lib-book-tech" lang="ru"><title>Технологии разработки</title>
    &intro.sgm;           <!-- О документе -->
    &sgml.sgm;            <!-- Ведение документации -->
    &db.sgm;              <!-- Описание информационной модели -->
    &lib-sql.sgm;         <!-- Разработка серверной части -->
    &lib-tools.sgm;       <!-- Дополнительные средства -->
  </book>

Pandoc — универсальный конвертер документов

Если вам нужно конвертировать файлы из одного формата разметки в другой, pandoc — ваш швейцарский армейский нож. Pandoc может конвертировать между большим числом форматов, их полный перечень вы найдёте на сайте программы: https://pandoc.org/

Установите пакет pandoc.

Затем выполните одну из команд следующего вида:

pandoc --from docbook --to docx --output myDocbook.docx myDocbook.xml

pandoc --from docbook --to odt --output myDocbook.odt myDocbook.xml

pandoc --from docbook --to latex --output myDocbook.pdf myDocbook.xml

pandoc --from docbook --to epub3 --output myDocbook.epub myDocbook.xml

pandoc --from docbook --to markdown --output myDocbook.md myDocbook.xml

pandoc --from docbook --to html --output myDocbook.html myDocbook.xml

Как вы могли уже понять:

—from — это исходный формат
—to — формат, в который нужно конвертировать
—output — имя файла для нового формата
myDocbook.xml — исходный документ DocBook.

Всё очень просто. Но для PDF я рекоменду dblatex!

Все ли понимают Asciidoc

Существует множество готовых инструментов, которыми можно проверять текстовые документы: например, vale, textlint, Aspell, LanguageTool.

Часть из этих инструментов поддерживают синтаксис Asciidoc. Но степень этой поддержки разная. Asciidoctor — самый богатый язык среди языков текстовой разметки, реализация в перечисленных средствах поддержки синтаксиса Asciidoctor может быть неполной или вообще неверной с точки зрения ваших требований к тексту.

Обычно, подобные проблемы легко преодолеть. Например, для есть плагин, представление элементов в объектном дереве определено в этом файле. Его можно легко поменять. Но иногда самой модели может не хватить для проведения всех необходимых видов тестирования.

Как я уже говорил проверять статическим анализатором лучше выходные документы. В Asciidoctor нет встроенной функции, которая превращает исходники в формате Asciidoc в составной Asciidoc-файл. Но Дэн Аллен сделал специальный скрипт, который справляется с данной задачей.

Пример — генерация документации по структуре базы данных

Пример иллюстрирует достаточно частую ситуацию, когда информация для документации хранится в таблицах СУБД.

Создаём скрипт, описывающий структуру БД. Этот скрипт не выглядит как исходник для поддержания структуры БД, однако, как это не парадоксально, таковым является, . Это также может быть миграционный скрипт в любой системе контроля версии базы данных.

Применим скрипт к базе данных и воспользуемся двумя инструментами СУБД (пример приведён для PostgreSQL): динамическими представлениями для извлечения сведений о структуре и возможностью создавать JSON-файлы на основе результатов сохранения запросов.

В результате получим JSON-файл:

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

Использование шаблонизаторов

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

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

Самым известным языком обработки шаблонов (но далеко не самым простым) является XSLT. Самым минималистичным — Mustache.

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

Можно вообще обойтись без шаблонизатора, просто структурировать код определенным образом, в этой старой статье 2003 года Мартин Фаулер признается в нелюбви к XSLT и заодно объясняет, как его заменить кодом, написанным на языке Ruby. За 18 лет оказалось, что и статические языки также можно прекрасно использовать для этих целей, и XSLT прекрасно себя чувствует, и предложенный в статье подход оказался очень хорош.

В примерах будет использоваться Liquid для работы с JSON и XSLT для работы с XML. В обоих случаях будет использоваться реализация в Ruby, потому что (1) Наиболее распространенный в настоящий момент процессор Asciidoc — Asciidoctor — написан на Ruby (2) Ruby-скрипты отлично работают в java и javascript, что часто позволяет не плодить цирк технологий.

Пример

Заголовок

Рассмотрим заголовок XML Docbook документа:

 <?xml version='1.0' encoding="windows-1251"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0/EN"
                "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" >

Документ в формате SGML Docbook будет абсолютно такой же, только без первой строчки (XML-декларации).
Вообще XML—версия Docbook более строгая, но более легкая в понимании и изучении. (XML проще чем SGML, но не такой мощный). Так как XML также является SGML—приложением, все программые средства SGML могут быть использованы. Основное различие между SGML и XML версиями состоит в следующем (применимо для всех XML — приложений):

XML элементы должны быть всегда закрыты.
XML элементы должны иметь правильную вложенность.
значения атрибутов должны быть обязательно в кавычках.
Это означает, что вы не можете использовать <BR> как в HTML, вы должны использовать <BR></BR>. Второе требование означает, что вы не можете использовать следующую конструкцию :

<B><A HREF="some_url">click here</B></A>

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

<B><A HREF="some_url">click here</A></B>.

Итак, заголовок состоит из

XML-декларации
Ссылки на DTD Docbook (соответствующей версии).
Внутреннего подмножества (Internal Subset) — то что находится внутри квадратных скобок. Там определяются все entity (объекты или подстановки), раскрывающиеся в литералы или содержимое файлов.

Комментарии оформляются стандартно для SGML синтаксиса (и следовательно XML-синтаксиса), и встречаться где угодно, после декларации и внутреннего подмножества, (исключая содержимое литералов и блоков сырых данных):

 <!--Комментарии оформляются стандартно для `SGML` синтаксиса -->
 <title>Приложение глазами пользователя</title>                                            
 &lib-app-struct.sgm;              <!-- Структура приложения -->
 &lib-app-interface-forms.sgm;     <!-- Экранные формы -->
 &lib-app-interface-usage.sgm;     <!-- Способы работы с областями формы -->
 &lib-app-interface-database.sgm;  <!-- Особенности работы с базой данных -->

Использование шаблонов Asciidoctor

Альтернативный способ подключения к Asciidoctor любых статических анализаторов — это превращение документа в текстовый файл. При этом появляется возможность размещать в данный файл дополнительную информацию, которая позволит понять, в каких исходниках произошла ошибка.

Для того, чтобы извлечь текст для проверки, Asciidoc поддерживает механизм шаблонов. Наименование папки с шаблонами передают в ключе .

Например, в следующем примере показан шаблон , который помещает в файл только куски текста, не содержащие роль .

Далее в примере показано использование утилиты непосредственно для выполнения функции проверки.

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

Тест, написанный таким образом, удобен тем, что в выводе будет информация об ошибочно написанных словах:

Аналогичный подход можно использовать для реализации всевозможных самостоятельных проверок — отсутствие запрещенных слов, запрет параграфов, задаваемых несколькими строками и т.п.

Последняя проверка заслуживает отдельного внимания, т.к. её отсутствие — частый источник ошибок. Рассмотрим следующий пример.

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

Так как после первого предложения отсутствует пустая строка, на выходе получится:

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

В примере к исходному тексту параграфа добавлены два символа переноса строки, чтобы отличать этот (правильный) случай от случая с одним переносом.

И далее в тесте необходимо искать параграфы, в которых есть переносы строк:

Обратите внимание, после знака перенос разрешён, т.к. это специальный синтаксис Asciidoctor, который позволяет вставить в абзац мягкие переносы

Следующий тест выявляет различные несуразности в тексте.

Встроенные проверки Asciidoctor

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

Можно также запустить тестирование из библиотеки :

Проверка структуры документов при помощи Docbook

Поскольку Asciidoctor изначально создавался как средство написания документов в формате Docbook, но в простом текстовом формате, то поддержка экспорта в формат Docbook реализована очень качественно.

Docbook — это вариант XML. Для тестирования структуры xml-файлов обычно используют два подхода.

Editing Programs

Bluefish
- This editor has syntax highlighting and code snippets for DocBook and many other languages.
- See http://bluefish.openoffice.nl/index.html
conglomerate (WYSIWYG)
- Somewhat beta. Doesn’t hide the gory details. You still need to read the DocBook reference. Just makes it graphical.
- See http://www.conglomerate.org/
VIM file type plugin «xmledit»
- Good for vim-lovers. See http://www.vim.org/scripts/script.php?script_id=301
- A recent update based on the above script. http://www.vim.org/scripts/script.php?script_id=1397
EMACS XML support
- Some say DocBook is easy to write only under psgml. Some use Emacs only for psgml-mode.
- nxml-mode however is far superior to psgml-mode. It does real-time syntax and error highlighting.
See also DocBookEditors.

Структура абзаца

Скорая помощь

Вы можете использовать xmllint с параметром ‘-o, чтобы
сохранить вывод в файле XML. Это особенно полезно, когда используется параметр —xpointer, так что
xmllint выполняет директивы XInclude, а затем сохраняет скомбинированный файл.

Набор бесформенных абзацев – занятие нудное, но это легко исправляется тем, что DocBook предоставляет специальные тэги для форматирования. Кроме базовых элементов, типа нумерованных списков и
выделения жирным шрифтом или курсивом, вы можете особо выделить листинги программ, цитаты других людей, экранные снимки и
многое другое. У DocBook есть тэги для всего, что как-то связано с
программами или компьютерами, так что он далеко не прост!

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

Чтобы организовать собственный сервер Ловли, вы
должны открыть TCP
порт 556 в брандмауэре

Внимание:
emphasis> мы не отвечаем за возможные последствия.
Вы можете найти предустановленные настройки брандмауэра в
файле firewall.config в каталоге с игрой.Если проблемы все еще есть, попытайтесь подключиться к
нашему сайту для проверки брандмауэра
http://www.qaziqargs.com/firewall
systemitem>.. Тэг задает либо жирный шрифт, либо курсив: если вы
уточните его словом ‘bold’, то текст будет выделен жирным; в противном случае – курсивом

Элемент – довольно хитрый зверь: в зависимости от роли, он может хранить IP-адреса, доменные
имена, имена пользователей и, как в моем примере, URL-ы. Кому интересно, знайте, что нет никаких способов указать «текст» ссылки (то есть фразу, которой она будет представлена в документе), потому что
DocBook спроектирован для работы с любыми носителями, включая
печатные (где, понятное дело, щелкать по URL бессмысленно!).

Тэг <emphasis> задает либо жирный шрифт, либо курсив: если вы
уточните его словом ‘bold’, то текст будет выделен жирным; в противном случае – курсивом. Элемент <systemitem> – довольно хитрый зверь: в зависимости от роли, он может хранить IP-адреса, доменные
имена, имена пользователей и, как в моем примере, URL-ы. Кому интересно, знайте, что нет никаких способов указать «текст» ссылки (то есть фразу, которой она будет представлена в документе), потому что
DocBook спроектирован для работы с любыми носителями, включая
печатные (где, понятное дело, щелкать по URL бессмысленно!).

Мы уже рассмотрели тэги <para> и <title>, однако интерес
представляют еще пять тэгов: <orderlist>, <itemizedlist>, <listitem>,
<programlisting> и <screen>. Первые три связаны между собой, поэтому
начнем с них: покажем, как сделать упорядоченный (нумерованный) и
неупорядоченный список (где порядок элементов не важен):

<para>Существует три способа погибнуть в игре Ловля мух:</para>
 <orderedlist>
   <listitem><para>Быть съеденным лягушкой</para></listitem>
    <listitem><para>Быть съеденным птицей</para></listitem>
    <listitem><para>Быть прихлопнутым мухобойкой</para></listitem>
 </orderedlist>
 <para>Если у вас в наличии один из следующих предметов, вы
 можете избежать смерти:</para>
 <itemizedlist>
    <listitem><para>Ружье</para></listitem>
    <listitem><para>Кустарник</para></listitem>
    <listitem><para>Слабительное</para></listitem>
 </itemizedlist>

Будь это HTML, то <orderlist> был бы <ol>, <listitem> стал бы <li> и
так далее – невелика разница, только что тэги DocBook длиннее! Текст
внутри <listitem> должен обрамляться тэгами <para>.

Элементы <programminglisting> и <screen> используются подобным
образом, но они являются отдельными сущностями и могут быть поразному отформатированы при выводе, если потребуется. Например:

<para>Для включения режима бессмертия в игре, войдите в консоь
 Ловли и наберите следующие коды:</para>
 <programlisting>
 idkfa
 iddqd
 idspispopd
 </programlisting>
 <para>Вы узнаете, что режим бессмертия активирован, когда увидите
 следующее
 сообщение на экране:</para>
 <screen>
 Сообщаем:
 режим бессмертия активирован!
 </screen>

Все символы-разделители сохраняются в элементах
<programminglist> и <screen>, так что набранный вами текст будет
отображен на экран в таком же виде.

Проверка при помощи схемы документа

XML поддерживает несколько стандартов схем документов. На сегодня самый распространенный — xsd-схемы.

Учитывая то, что Asciidoc поддерживает очень много элементов синтаксиса и не каждый конвертер корректно работает со всеми элементами (а Хабр вообще мало, что поддерживает), в примере ограничим используемые элементы параграфами, маркированными списками и врезками кода, также разрешим картинку после заголовка:

В тесте проверка выглядит следующим образом:

Обычно такой подход применяют к кускам документа. В DITA — есть термин (тема). В зависимости от типа темы мы можем определять её структуру. Все темы определенного типа будут иметь одинаковую структуру.

Это удобно, если в документации активно используются похожие блоки.

Оформление страницы

Скорая помощь

Если вы хотите сравнить два XML-документа, используйте xmldiff, а не обычную утилиту diff.
xmldiff запрограммирована так, чтобы находить разницу в структуре, а не просто разницу текстов.

Документация – это не только текст. На самом деле, из проповедей Кэти Сиерра вы узнаете, что текст – лишь небольшая часть вашей работы! DocBook позволяет добавлять таблицы и картинки, а если вы добавите к
ним атрибут id, то сможете ссылаться на них с помощью тэга <xref>.

Чтобы вставить рисунок, нам необходим сам рисунок и подпись к
нему. Вот как это выглядит в DocBook XML:

 <figure id=”ch01-fig12”>
    <title>Муха-гигант охотится за человеком</title>
    <graphic fileref=”figs/mxkyl.png”/>
 </figure>

Обратите внимание на атрибут id: сначала указан номер главы, а
затем номер рисунка. Такой формат необязателен, но с ним удобнее
отслеживать рисунки в большом проекте.. Работать с таблицами немного сложнее, потому что нам необходимо определить тип требуемой таблицы, указать, сколько в ней столбцов и строк и, наконец, ввести содержимое ячеек

Простейшая таблица
выглядит так:

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

 <informaltable>
    <tgroup cols=”2”>
       <tbody>
       <row>
          <entry>F1</entry>
          <entry>Помощь</entry>
       </row>
       <row>
          <entry>F2</entry>
          <entry>Сменить оружие</entry>
       </row>
       </tbody>
    </tgroup>
 </informaltable>

В терминах HTML, <informaltable> – это <table>, <row> – <tr>, а
<entry> – <td>. Мы можем превратить нашу <informaltable> в обычную
таблицу <table> с добавлением заголовка:

 <table>
    <title>Клавиатурные сокращения</title>
    <tgroup cols=”2”>

Исходя из наличия элемента <tbody>, можно предположить, что
должен быть и элемент <thead>, определяющий заголовки столбцов.
Наша таблица хранит названия клавиш и их действия; ее можно модифицировать следующим образом:

 <table>
    <title>Клавиатурные сокращения</title>
    <tgroup cols=”2”>
       <thead>
          <row>
             <entry>Клавиша</entry>
             <entry>Действие</entry>
          </row>
       </thead>
       <tbody>

Как <thead>, так и <tbody> существуют и в HTML (впрочем, используются там нечасто), так что они могут быть вам уже знакомы.

What are the Advantages of DocBook?

DocBook is an OASIS standard and the format in which most open source projects store their documentation. Docbook is developed as an open source application. The project is hosted at SourceForge and is made available under the GPL. DocBook is available as a Document Type Definition (DTD) and XML Schema (XSD). The project has a large developer and support community spanning both open source and commercial groups.

The most important reasons why the project uses DocBook include:

DocBook is a standard
DocBook is open source
DocBook is used by most major projects
DocBook has a large developer and support community

DocBook is also an XML application and XML technologies solve a number of publishing problems for documentation teams, including:

Single-sourcing
Collaborative authoring
Cross-platform editing
Multi-channel publishing
Improving information quality and consistency
Enhancing functionality of electronic output
Negating vendor lock-in

More information on these points can be found at http://www.sastc.org.za/index.php?option=com_content&task=view&id=18&Itemid=35

If you already understand XML then you are in a good position to start learning DocBook. If you do not understand XML the good news is that learning DocBook will help you learn XML. Below are two books that are a must read for anyone just starting with DocBook.

Написание SGML с использование LyX

Новые документы

Начать писать новое HOWTO с помощью LyX очень просто. Используйте команду меню File->New from template…, чтобы вызвать на экран список шаблонов. Выберите Templates на правой части экрана, затем выберите docbook_template.lyx в списке файлов. Нажмите OK и вы получите новый документ. Заполните такие вещи как заголовок,краткое описание и имя автора, и приступайте к написанию документа.

Существующие документы.

Если у вас уже есть LyX, TeX, или текстовый документ, вы можете импортировать его в LyX с помощью команды File->import. Импортировав файл, идите в Layout->Document… . В появившемся окне, под Style, выберите SGML (DocBook Article). Вас спросят хотите ли вы конвертировать весь текст, ответьте «Yes». Вам потребуется изменить большую часть тэгов, но это довольно простое дело: выделяйте текст и изменяйте стиль.Для многих Lyx функций существуют горячие клавиши, они помогут вам сделать это быстрее.

Проверка при помощи xpath-выражений

Xpath-выражения — инструмент, который позволяет делать выборки из файлов в формате xml.

Полученную выборку можно проанализировать на соответствие определенным правилам.

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

Эту задачу можно было бы решить, прописав в предыдущей схеме ограничение на один элемент типа , но часто формулировка локальных правил в виде xpath-выражений проще:

Этот же подход можно использовать для проверки сложных правил, не описываемых xsd-схемой, например, соответствие списка терминов тексту или работоспособность внешних ссылок:

Проверка соответствия документации коду

В статье Автоматическая генерация технической документации рассмотрены инструменты автоматической генерации текстовых фрагментов из кода. Обычно формирование этих фрагментов происходит не в момент сборки документации, а при её подготовке.

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

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

Проверка выходных файлов

Документация представляется пользователю в удобочитаемых форматах, например, html, pdf, odt, docx и т.п.

Если вы используете стандартные конвертеры Asciidoctor, возможно, выходной файл проверять не надо. Но желательно открыть и сохранить файл в нативном приложении. Например, в моём проекте сделана специальная точка вызова, которая конвертирует файл и автоматически открывает/сохраняет его при помощи LibreOffice Writer. Достаточно проверить, что выходной файл есть.

Офисные приложения — Microsoft Word, LibreOffice Writer — иногда портят документы при открытии. Например, Microsoft Word заменяет поля на текст «Ошибка. Закладка не определена». Если такие случаи часты, для исключения целесообразно делать соответствующие проверки.

Выводы

Предложенная технология универсальна и может быть использована для создания любых документов с высоким уровнем требований по качеству, в том числе, статей на Хабре.
Asciidoc дает много возможностей по проверке качества документации. В совокупности они позволяют проверить оформление исходных файлов, качество текста, структуру документов и т.п.
Наличие нативного статического анализатора для Asciidoc могло бы значительно упростить процесс задания правил для проверки документации.
Результат проверки данной статьи — , а ошибки всё равно есть. PRs are welcome.

Загрузка и установка необходимых утилит.

Непосредственное использование jade/openjade

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

Создайте базовую директорию где вы будете хранить все необходимое. Например: /usr/local/sgml. Далее по тексту мы будем называть её $_toolroot.
Установите Jade, DocBook DTD, и DSSSL, так чтобы базовой директорией всех их была $_toolroot (создав $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dssl)
Вам нужно установить переменную окружения SGML_CATALOG_FILES указывающую на каталоги которые находятся в $_toolroot. Вы можете сделать это с помощью следующей команды: $ENV{‘SGML_CATALOG_FILES’} = “$_toolroot/dtd/docbook.cat;$_toolroot/dsssl/docbook/catalog;$_toolroot/jade-1.2.1/dsssl/catalog”
Теперь вы готовы к использованию Jade. Чтобы создать отдельные HTML файлы: $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml
Чтобы создать один большой HTML файл,добавьте -V nochunks в приведенную выше команду.

sgmltools

Вам понадобятся sgmltools версии 2.x для использования с DocBook. Так как все бэк-энд программы также сменились, вам придется забыть о программах типа sgml2xxx. А так как с большинством дистрибутивов поставляются sgml 1.x, вам придется удалить пакет sgml 1.x и установить CVS версию или версию 2.0. Чтобы получить последнюю версию CVS кода,вы можете использовать следующие команды.

CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs
export CVSROOT
cvs login
cvs -z6 get sgmltools

Пароль для CVS — ‘cvs’. Загрузив исходный код, вы можете использовать

./compile 
make
make install

чтобы установить sgmltools. Для Red Hat (или основанных на них) систем вы можете использовать команду rpmfind чтобы получить последнюю версию sgmltools. Эту программу можно найти по адресу http://www.rpmfind.net/. Убедитесь в том, что вы скачали именно sgmltools а не sgml-tools, т.к. последний — это sgmltools версии 1.0.9. Для систем базирующихся на Debian, используйте apt-get, чтобы получить нужный вам пакет:

# apt-get install sgmltools

Также как и в случае с RedHat, убедитесь, что скачали sgmltools а не sgml-tools.