Журнал 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

Подписка на печатную версию
Весь 2015 год (12 номеров)
Первое полугодие (6 номеров)
Второе полугодие (6 номеров)
Подписка на электронную версию
Весь 2015 год (12 номеров)
Первое полугодие (6 номеров)
Второе полугодие (6 номеров)
Подшивки старых номеров журнала (печатные версии)
Весь 2014 год (12 номеров)
Первое полугодие (6 номеров)
Второе полугодие (6 номеров)
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>, ссылки обычно создаются на начало раздела, содержащего требуемый блок.

Источник — «http://wiki.linuxformat.ru/wiki/index.php?title=LXF87-88:DocBook&oldid=5878»
Персональные инструменты
купить
подписаться
Яндекс.Метрика