Журнал LinuxFormat - перейти на главную

LXF87-88:DocBook

Материал из Linuxformat
(Различия между версиями)
Перейти к: навигация, поиск
(викификация, оформление)
 
(викификация, оформление)
Строка 97: Строка 97:
 
Как вы понимаете, разобраться с ''XML'' здесь не самое сложное –
 
Как вы понимаете, разобраться с ''XML'' здесь не самое сложное –
 
куда сложнее написать качественную документацию!
 
куда сложнее написать качественную документацию!
 +
 +
==Структура абзаца==
 +
 +
{{Врезка
 +
|Заголовок=Скорая помощь
 +
|Содержание=Вы можете использовать ''xmllint'' с параметром '''-o'', чтобы
 +
сохранить вывод в файле ''XML''. Это особенно полезно, когда используется параметр '''--xpointer''', так что
 +
''xmllint'' выполняет директивы '''XInclude''', а затем сохраняет скомбинированный файл.
 +
|Ширина=200px
 +
}}
 +
 +
Набор бесформенных абзацев – занятие нудное, но это легко исправляется тем, что ''DocBook'' предоставляет специальные тэги для форматирования. Кроме базовых элементов, типа нумерованных списков и
 +
выделения жирным шрифтом или курсивом, вы можете особо выделить листинги программ, цитаты других людей, экранные снимки и
 +
многое другое. У ''DocBook'' есть тэги для всего, что как-то связано с
 +
программами или компьютерами, так что он далеко не прост!
 +
 +
На наше счастье, достаточно знать только о тех элементах, которые
 +
будут вами использоваться. Основные элементы можно разделить на
 +
две катэгории: встраиваемые и блочные. Блочные элементы образуют естественные части текста, которые в результирующем документе отделяются пустой строкой. Встраиваемые элементы изменяют отдельные слова внутри блочных, не влияя на организацию текста. Начнем с основных элементов:
 +
 +
<source lang=xml>
 +
<para>Чтобы организовать собственный сервер Ловли, вы
 +
    <emphasis>должны</emphasis> открыть <acronym>TCP</acronym>
 +
    порт 556 в брандмауэре. <emphasis role=”bold”>Внимание:</
 +
    emphasis> мы не отвечаем за возможные последствия.</para>
 +
<para>Вы можете найти предустановленные настройки брандмауэра в
 +
файле <filename>firewall.config</filename> в каталоге с игрой.</para>
 +
<para>Если проблемы все еще есть, попытайтесь подключиться к
 +
нашему сайту для проверки брандмауэра
 +
    <systemitem role=”url”>http://www.qaziqargs.com/firewall</
 +
    systemitem>.</para>
 +
</source>
 +
 +
Тэг '''<emphasis>''' задает либо жирный шрифт, либо курсив: если вы
 +
уточните его словом '''‘bold’''', то текст будет выделен жирным; в противном случае – курсивом. Элемент '''<systemitem>''' – довольно хитрый зверь: в зависимости от роли, он может хранить IP-адреса, доменные
 +
имена, имена пользователей и, как в моем примере, URL-ы. Кому интересно, знайте, что нет никаких способов указать «текст» ссылки (то есть фразу, которой она будет представлена в документе), потому что
 +
''DocBook'' спроектирован для работы с любыми носителями, включая
 +
печатные (где, понятное дело, щелкать по URL бессмысленно!).
 +
 +
Мы уже рассмотрели тэги '''<para>''' и '''<title>''', однако интерес
 +
представляют еще пять тэгов: '''<orderlist>''',''' <itemizedlist>''',''' <listitem>''',
 +
'''<programlisting>''' и '''<screen>'''. Первые три связаны между собой, поэтому
 +
начнем с них: покажем, как сделать упорядоченный (нумерованный) и
 +
неупорядоченный список (где порядок элементов не важен):
 +
 +
<source lang=xml>
 +
<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>
 +
</source>
 +
 +
Будь это ''HTML'', то '''<orderlist>''' был бы '''<nowiki><ol></nowiki>''', '''<listitem>''' стал бы '''<nowiki><li></nowiki>''' и
 +
так далее – невелика разница, только что тэги ''DocBook'' длиннее! Текст
 +
внутри '''<listitem>''' должен обрамляться тэгами '''<para>'''.
 +
 +
Элементы '''<programminglisting>''' и '''<screen>''' используются подобным
 +
образом, но они являются отдельными сущностями и могут быть поразному отформатированы при выводе, если потребуется. Например:
 +
 +
<source lang=xml>
 +
<para>Для включения режима бессмертия в игре, войдите в консоь
 +
Ловли и наберите следующие коды:</para>
 +
<programlisting>
 +
idkfa
 +
iddqd
 +
idspispopd
 +
</programlisting>
 +
<para>Вы узнаете, что режим бессмертия активирован, когда увидите
 +
следующее
 +
сообщение на экране:</para>
 +
<screen>
 +
Сообщаем:
 +
режим бессмертия активирован!
 +
</screen>
 +
</source>
 +
 +
Все символы-разделители сохраняются в элементах
 +
'''<programminglist>''' и '''<screen>''', так что набранный вами текст будет
 +
отображен на экран в таком же виде.
 +
 +
==Работа с несколькими главами==
 +
 +
{{Врезка
 +
|Заголовок=''DocBook'' в роли нормативного формата
 +
|Содержание=''DocBook'' обычно считается «нормативным» форматом, то есть он не предлагается конечному потребителю. Для просмотра его необходимо преобразовать в другой формат. Это позволяет вам сосредоточиться на документации, а не на ее представлении.
 +
 +
[[Изображение:LXF88_docbook1.png|LXF88_docbook1.png]]
 +
 +
''' ''DocBook XML'' как нормативный формат означает, что его можно конвертировать...'''
 +
 +
[[Изображение:LXF88_docbook2.png|LXF88_docbook2.png]]
 +
 +
'''как в ''HTML''..., '''
 +
 +
[[Изображение:LXF88_docbook3.png|LXF88_docbook3.png]]
 +
 +
так и в ''PDF''
 +
|Ширина=200px
 +
}}
 +
 +
Прежде чем начать печатать, подумайте об организации работы.
 +
Прекрасно, что вы можете разбить вашу книгу на главы, разделы и
 +
абзацы, но важно разделить на части и работу, создав предпосылки
 +
для привлечения команды. То есть – использовать несколько файлов,
 +
разделенных согласно вашим нуждам – например, можно выделить по
 +
файлу для каждой документируемой функции.
 +
 +
Файл, в который включают другие файлы, использует стандарт
 +
'''XInclude''', в котором вы можете определить URL, загружаемый при обработке файла. Это позволит вам переложить часть работы на коллег, а затем собрать все документы вместе. Чтобы распределить главы по
 +
отдельным файлам, ваша XML-книга должна выглядеть примерно так:
 +
 +
<source lang=xml>
 +
<?xml version=”1.0”?>
 +
<!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML
 +
V4.4//EN”
 +
“http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd”>
 +
<book>
 +
    <title> Ловля мух!</title>
 +
    <include xmlns=”http://www.w3.org/2001/XInclude”
 +
href=”chapter01.xml”/>
 +
    <include xmlns=”http://www.w3.org/2001/XInclude”
 +
href=”chapter02.xml”/>
 +
    <include xmlns=”http://www.w3.org/2001/XInclude”
 +
href=”chapter03.xml”/>
 +
    <include xmlns=”http://www.w3.org/2001/XInclude”
 +
href=”chapter04.xml”/>
 +
</book>
 +
</source>
 +
 +
Начало положено, но это не облегчит людям чтение: если вы скажете «смотри раздел 3 главы 4», то им придется искать, где находится это место. Обычно ''DocBook''-конверторы создают оглавление, содержащее
 +
номера страниц (или ''HTML''-ссылки), но такой подход требует, чтобы
 +
пользователи поднимались к оглавлению, находили ссылку, переходили по ней, а затем нажимали кнопку Назад два раза, чтобы вернуться туда, откуда пришли.
 +
 +
Мы можем облегчить им задачу, используя тэг '''<xref>''', позволяющий делать ссылки на главы, разделы и некоторые другие блоки. Взглянув на наш первый пример с книгой, вы заметите строку:
 +
 +
<chapter id=”ch01”>
 +
 +
Именно атрибут '''“id”''' позволяет нам устанавливать ссылки.
 +
Например, если мы хотим сделать ссылку на главу 1, то можем написать следующее:
 +
 +
<para>Если ваша игра не устанавливается, вернитесь и прочтите
 +
инструкции в <xref linkend=”ch01” />.</para>
 +
 +
Нам не требуется писать «прочтите инструкции в главе 1» – такой
 +
текст будет получен после преобразования документа в требуемый
 +
формат. Например, если документ преобразуется в ''HTML'', '''<xref>''' станет
 +
гиперссылкой с текстом типа «главе Руководство по установке», указывающей на начало этой самой главы.
 +
 +
Можно применить атрибуты '''id''' и к разделам, но когда вы делаете
 +
ссылки на отдельные блоки '''<para>''', ссылки обычно создаются на начало раздела, содержащего требуемый блок.

Версия 15:52, 9 декабря 2008

Hardcore Linux Проверьте себя, участвуя в сложных проектах для продвинутых пользователей.

Содержание

DocBook: Пишем документацию

Что общего у ядра, FreeBSD, KDE и Gnome? Документация! Пол Хадсон рассказывает о новой технологии для ее написания.

Создание документации к программам всегда было пробле мой для программистов: ведь это же тупость – объяснять, как все работает, когда оно ослепительно-очевидно. Наши программы, естественно, всегда понятны нам, потому что мы сами их написали; но есть люди, до сих пор думающие, что компьютеры и программы – это какое-то колдовство. Поэтому необходимо кратко объяснить им, какие кнопки нажимать для выполнения нужных операций. На этом уроке мы изучим DocBook – формат написания документации. Он основан на XML, и с ним можно работать в любом текстовом редакторе. Он используется во многих крупных проектах, включая ядро Linux, FreeBSD и KDE, поэтому рано или поздно вы с ним столкнетесь.

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

Ныряем в DocBook

DocBook (как XML) имеет строгую структуру, которой необходимо следовать, но она довольно понятна. Помните, что DocBook – это разновидность XML, разработанная специально для создания документации, поэтому его структурными элементами являются главы, разделы, заголовки, абзацы и так далее. Вот и все, что необходимо знать для создания нашей первой части документации: книги, состоящей из одной главы. Начнем:

 <?xml version=”1.0” ?>
 <!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML
 V4.4//EN”
 “http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd”>
 <book>
    <title>Ловля мух!</title>
    <chapter id=”ch01”>
       <title>Введение</title>
       <sect1>
          <title> Добро пожаловать в лучшую в мире игру!</title>
          <para>Да, она действительно так хороша.</para>
       </sect1>
    </chapter>
 </book>

[Необходимо использовать кодировку UTF-8 или указать ее явно в тэге <?xml?> при помощи атрибута ‘encoding’, – прим. ред.] Тип DTD, который мы собираемся использовать – стандарт DocBook 4.4, доступный из сотворившей его организации Oasis. Если хотите, можете скопировать файл .dtd на свою машину – это немного ускорит вашу работу, потому что в противном случае вашему компьютеру для валидации документа придется копировать DTD из сети.

Разберем написанное: наша полностью законченная документация называется книгой (book). Как и большинство книг, она состоит из отдельных глав, разбитых на разделы. В нашем примере с Ловлей мух у нас могут быть следующие главы: Введение, Описание игрового процесса, Многопользовательская игра, Разрешение проблем и Контактная информация.

Каждая глава состоит из разделов и подразделов, это упрощает чтение материала. Например, раздел Многопользовательская игра' может состоять из секций ‘Запускаем сервер’, ‘Подсоединяемся к серверу’ и ‘Настраиваем брандмауэр’. ‘Запускаем сервер’ можно затем подразделить на ‘Выделенный сервер’, ‘Невыделенный сервер’, ‘Обнаружение вашего IP-адреса’ и так далее. В терминологии DocBook эти разделы называются ‘sections’ и вы можете выбирать из <sect1> (раздел верхнего уровня), <sect2>, <sect3> или <sect4>. Обычно в оглавление попадают только первые три уровня – четвертый чуть больше размером, чем жирный текст, и если вы поймаете себя на том, что вовсю используете <sect4>, то придется признать: ваша документация чересчур многословна!

Итак, книга <book> содержит главы <chapter>, которые содержат разделы <sect1>, содержащие подразделы <sect2>, в свою очередь, содержащие <sect3>, а те <sect4>. Вот как все может выглядеть:

 <chapter id=”ch01”>
    <title>Введение</title>
    <sect1>
       <title> Добро пожаловать в лучшую в мире игру!</title>
       <para>Да, она действительно так хороша.</para>
       <sect2>
          <title>Почему же она так хороша?</title>
          <para>На это есть множество причин!</para>
          <sect3>
             <title>Взрослым...</title>
             <para>Много крови, убийств и жутких моментов!</para>
          </sect3>
          <sect3>
             <title>Детям...</title>
             <para>Еще больше крови, убийств и жутких моментов!</para>
          </sect3>
       </sect2>
    </sect1>
 </chapter>

Необходимо строго соблюдать иерархию структуры – вы не можете создать <chapter>, затем сразу <sect3>, или же <sect3>, а затем <sect2>, как показано ниже:

 <chapter id=”ch01”>
    <sect3>
       <sect2>
          <title>Введение</title>
       </sect2>
    </sect3>
 </chapter>

И книга, и глава, и раздел могут иметь свой собственный <title>, то есть заголовок. После этого начинается основная работа: множество элементов <para>, каждый из которых представляет один текстовый абзац.

Как вы понимаете, разобраться с XML здесь не самое сложное – куда сложнее написать качественную документацию!

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

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

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

 <para>Чтобы организовать собственный сервер Ловли, вы
    <emphasis>должны</emphasis> открыть <acronym>TCP</acronym>
    порт 556 в брандмауэре. <emphasis role=”bold”>Внимание:</
    emphasis> мы не отвечаем за возможные последствия.</para>
 <para>Вы можете найти предустановленные настройки брандмауэра в
 файле <filename>firewall.config</filename> в каталоге с игрой.</para>
 <para>Если проблемы все еще есть, попытайтесь подключиться к
 нашему сайту для проверки брандмауэра
    <systemitem role=”url”>http://www.qaziqargs.com/firewall</
    systemitem>.</para>

Тэг <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>, так что набранный вами текст будет отображен на экран в таком же виде.

Работа с несколькими главами

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

Файл, в который включают другие файлы, использует стандарт XInclude, в котором вы можете определить URL, загружаемый при обработке файла. Это позволит вам переложить часть работы на коллег, а затем собрать все документы вместе. Чтобы распределить главы по отдельным файлам, ваша XML-книга должна выглядеть примерно так:

 <?xml version=”1.0”?>
 <!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML
 V4.4//EN”
 “http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd”>
 <book>
    <title> Ловля мух!</title>
    <include xmlns=”http://www.w3.org/2001/XInclude”
 href=”chapter01.xml”/>
    <include xmlns=”http://www.w3.org/2001/XInclude”
 href=”chapter02.xml”/>
    <include xmlns=”http://www.w3.org/2001/XInclude”
 href=”chapter03.xml”/>
    <include xmlns=”http://www.w3.org/2001/XInclude”
 href=”chapter04.xml”/>
 </book>

Начало положено, но это не облегчит людям чтение: если вы скажете «смотри раздел 3 главы 4», то им придется искать, где находится это место. Обычно DocBook-конверторы создают оглавление, содержащее номера страниц (или HTML-ссылки), но такой подход требует, чтобы пользователи поднимались к оглавлению, находили ссылку, переходили по ней, а затем нажимали кнопку Назад два раза, чтобы вернуться туда, откуда пришли.

Мы можем облегчить им задачу, используя тэг <xref>, позволяющий делать ссылки на главы, разделы и некоторые другие блоки. Взглянув на наш первый пример с книгой, вы заметите строку:

<chapter id=”ch01”>

Именно атрибут “id” позволяет нам устанавливать ссылки. Например, если мы хотим сделать ссылку на главу 1, то можем написать следующее:

<para>Если ваша игра не устанавливается, вернитесь и прочтите
инструкции в <xref linkend=”ch01” />.</para>

Нам не требуется писать «прочтите инструкции в главе 1» – такой текст будет получен после преобразования документа в требуемый формат. Например, если документ преобразуется в HTML, <xref> станет гиперссылкой с текстом типа «главе Руководство по установке», указывающей на начало этой самой главы.

Можно применить атрибуты id и к разделам, но когда вы делаете ссылки на отдельные блоки <para>, ссылки обычно создаются на начало раздела, содержащего требуемый блок.

Персональные инструменты
купить
подписаться
Яндекс.Метрика