4.2. DocBook

4.2.3.1. Начало книги

Текст книги размещается внутри элемента <book>. Этот элемент, наряду с тем, что содержит структурированную разметку, может содержать элементы, которые включают дополнительную информацию о книге. Это либо мета-информация, используемая для справочных целей, либо дополнительный текст, используемый для генерации заглавной страницы.

Эта дополнительная информация должна располагаться в <bookinfo>.

<book>
  <bookinfo>
    <title>Здесь ваш заголовок</title>

    <author>
      <firstname>Ваше имя</firstname>
      <surname>Ваша фамилия</surname>
      <affiliation>
    <address><email>Ваш адрес электронной почты</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:Ваш e-mail">Ваше имя</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Сюда включите обзор содержимого книги.</para>
    </abstract>
  </bookinfo>

  ...

</book>

4.2.3.2. Начало статьи

Содержимое статьи размещается внутри элемента <article>. Этот элемент, наряду с тем, что содержит структурированную разметку, может содержать элементы, которые включают дополнительную информацию о статье. Это либо мета-информация, используемая для справочных целей, либо дополнительный текст, используемый для генерации заглавной страницы.

Эта дополнительная информация должна размещаться внутри <articleinfo>.

<article>
  <articleinfo>
    <title>Здесь ваш заголовок</title>

    <author>
      <firstname>Ваше имя</firstname>
      <surname>Ваша фамилия</surname>
      <affiliation>
    <address><email>Ваш e-mail</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:Ваш e-mail">Ваше имя</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Сюда включите обзор содержимого статьи.</para>
    </abstract>
  </articleinfo>

  ...

</article>

4.2.3.3. Оформление глав

Используйте <chapter> для разметки ваших глав. Каждая глава имеет обязательный элемент <title>. Статьи не содержат глав, они используются только в книгах.

<chapter>
  <title>Заголовок главы</title>

  ...
</chapter>

Глава не может быть пустой; она должна содержать элементы, кроме <title>. Если вы хотите включить пустую главу, то воспользуйтесь пустым параграфом.

<chapter>
  <title>Это пустая глава</title>

  <para></para>
</chapter>

4.2.3.4. Секции ниже глав

В книгах главы могут (но но обязаны) разбиваться на разделы, подразделы и так далее. В статьях разделы являются главными структурными элементами, и каждая статья должна содержать по крайней мере один раздел. Используйте элемент <sectn>. n задает номер раздела, определяющий его уровень вложенности.

Первый раздел <sectn> это <sect1>. В главе вы можете иметь один или большее количество таких разделов. Они могут содержать один или большее количество элементов <sect2> и так далее, вплоть до <sect5>.

<chapter>
  <title>Примерная глава</title>

  <para>Некоторый текст в главе.</para>

  <sect1>
    <title>Первый раздел (1.1)</title>

    ...
  </sect1>

  <sect1>
    <title>Второй раздел (1.2)</title>

    <sect2>
      <title>Первый подраздел (1.2.1)</title>

      <sect3>
    <title>Второй подподраздел (1.2.1.1)</title>

    ...
      </sect3>
    </sect2>

    <sect2>
      <title>Второй подраздел (1.2.2)</title>

      ...
    </sect2>
  </sect1>
</chapter>

4.2.3.5. Разбиение при помощи <part>

Вы можете создать еще один уровень организации между <book> и <chapter> при помощи одного или большего количества элементов <part>. Этого нельзя сделать в <article>.

<part>
  <title>Введение</title>

  <chapter>
    <title>Обзор</title>

    ...
  </chapter>

  <chapter>
    <title>Что такое FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>История</title>

    ...
  </chapter>
</part>

4.2.4.1. Параграфы

DocBook поддерживает три типа параграфов: <formalpara>, <para> и <simpara>.

В большинстве случаев вам потребуется использовать только <para>. <formalpara> включает элемент <title>, а <simpara> запрещает использование некоторых элементов из <para>. Остановите свой выбор на <para>.

<para>Это параграф.  Он может содержать
  практически любой другой элемент.</para>

4.2.4.2. Блочное цитирование

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

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

<para>Короткий отрывок из Конституции США;</para>

<blockquote>
  <title>Preamble to the Constitution of the United States</title>

  <attribution>Copied from a web site somewhere</attribution>
    
  <para>We the People of the United States, in Order to form a more perfect
    Union, establish Justice, insure domestic Tranquility, provide for the
    common defence, promote the general Welfare, and secure the Blessings
    of Liberty to ourselves and our Posterity, do ordain and establish this
    Constitution for the United States of America.</para>
</blockquote>

4.2.4.3. Советы, замечания, предупреждения, предостережения, важная информация и заметки на полях.

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

В зависимости от природы информации, должен использоваться элемент <tip>, <note>, <warning>, <caution> или <important>. Либо, если информация связана с основным текстом, но не является чем-либо из перечисленного, используйте элемент <sidebar>.

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

• Note (замечание) для информации, на которую должны обратить внимание все читатели.

• Элемент Important (важное) является разновидностью элемента Note.

• Caution (предостережение) для информации относительно возможных потерь данных или порчи программного обеспечения.

• Warning (предупреждение) для информации, касающейся возможной порчи оборудования или нанесения вреда жизни или органам.

<warning>
  <para>Установка FreeBSD может привести к желанию удалить Windows с вашего
    винчестера.</para>
</warning>

4.2.4.4. Списки и процедуры

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

Для этого используйте элементы <itemizedlist>, <orderedlist> или <procedure> [2]

<itemizedlist> и <orderedlist> похожи на соответствующие элементы из HTML, <ul> и <ol>. Каждый из них состоит из одного или большего количества элементов <listitem>, и каждый <listitem> содержит один или большее количество блочных элементов. Элементы <listitem> аналогичны меткам <li> из HTML. Однако, в отличие от HTML, они обязательны.

<procedure> несколько от них отличается. Он состоит из элементов <step> (шаг), которые, в свою очередь, состоят из дополнительных элементов <step> или <substep>. Каждый элемент <step> содержит блочные элементы.

<itemizedlist>
  <listitem>
    <para>Это первый списочный элемент.</para>
  </listitem>

  <listitem>
    <para>Это второй списочный элемент.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>Это первый упорядоченный элемент.</para>
  </listitem>

  <listitem>
    <para>Это второй упорядоченный элемент.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Сделайте это.</para>
  </step>

  <step>
    <para>Затем сделайте то.</para>
  </step>

  <step>
    <para>А теперь сделайте вот так.</para>
  </step>
</procedure>

4.2.4.5. Показ примеров файлов

Если вы хотите показать пользователю фрагмент файла (или, возможно, файл полностью), поместите его в элемент <programlisting>.

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

<para>Когда вы закончите, ваша программа должна
  иметь примерно такой вид:</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("hello, world\n");
}</programlisting>

#include <stdio.h>

int
main(void)
{
    printf("hello, world\n");
}

4.2.4.6. Отсылки

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

Чтобы это сделать, пометьте интересующие области в вашем примере (<programlisting>, <literallayout> или что там у вас еще) элементом <co>. Каждый элемент должен иметь уникальный присвоенный ему идентификатор id. После примера поместите <calloutlist>, который ссылается на пример и дает дополнительный комментарий.

<para>Когда вы закончите, ваша программа
  должна иметь примерно такой вид;</para>

<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">

int <co id="co-ex-return">
main(void)
{
    printf("hello, world\n"); <co id="co-ex-printf">
}</programlisting>

<calloutlist>
  <callout arearefs="co-ex-include">
    <para>Включение стандартного файла объявлений IO.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Указывает на то, что <function>main()</function> возвращает
      int.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>Вызов <function>printf()</function>, который выдает
      <literal>hello, world</literal> на стандартный вывод.</para>
  </callout>
</calloutlist>

#include <stdio.h> 

int 
main(void)
{
    printf("hello, world\n"); 
}

4.2.4.7. Таблицы

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

Вообще (обратитесь к документации по DocBook для получения дополнительной информации) таблица (которая может быть формальная или неформальная) состоит из элемента <table>. Он содержит по крайней мере один элемент <tgroup>, задающий (как атрибут) количество столбцов в этой табличной группе. Внутри табличной группы вы можете иметь один элемент <thead>, который содержит элементы для заголовков таблицы (заголовки столбцов) и один элемент <tbody>, содержащий тело таблицы.

Как <tgroup>, так и <thead> содержат элементы <row>, в свою очередь, содержащие элементы <entry>. Каждый элемент <entry> задает одну ячейку в таблице.

<informaltable frame="none" pgwide="1">
  <tgroup cols="2">
    <thead>
      <row>
    <entry>Это заголовок столбца 1</entry>
    <entry>Это заголовок столбца 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
    <entry>Строка 1, столбец 1</entry>
    <entry>Строка 1, столбец 2</entry>
      </row>

      <row>
    <entry>Строка 2, столбец 1</entry>
    <entry>Строка 2, столбец 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

Вместе с элементом <informaltable> всегда используйте атрибут pgwide со значением 1. Если атрибут будет опущен, то из-за ошибки в в браузере Internet Explorer таблица будет отображаться некорректно.

Если вам не нужна граница вокруг таблицы, то к элементу <informaltable> может быть добавлен атрибут frame со значением none (то есть <informaltable frame="none">).

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

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

При этом задействуется некоторое количество различных элементов и сущностей.

<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>

% ls -1
foo1
foo2
foo3
% ls -1 | grep foo2
foo2
% su
Password: 
# cat foo2
This is the file called 'foo2'

4.2.5.1. Выделение информации

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

Внутри документа нет способа изменить способ выделения, нет эквивалентам <b> и <i> из HTML. Если информация, которую вы выделяете, важна, то используйте <important> вместо <emphasis>.

<para>FreeBSD, без сомнения, является
  <emphasis>наилучшей</emphasis> операционной Unix-подобной системой для
  архитектуры Intel.</para>

4.2.5.2. Цитирование

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

<para>Несмотря на это убедитесь, что поиск не выходит за
  <quote>пределы между локальным и публичным администрированием</quote>,
  как RFC 1535 описывает это.</para>

4.2.5.3. Клавиши, кнопки мыши и комбинации

Чтобы описать некоторую клавишу на клавиатуре, используйте <keycap>. Чтобы описать кнопку мыши, воспользуйтесь <mousebutton>. А чтобы описать комбинацию нажатий клавиш или щелчков мыши, заключите их в <keycombo>.

<keycombo> имеет атрибут под названием action, который может принимать одно из значений click, double-click, other, press, seq или simul. Последние два значения определяют, должны ли клавиши или кнопки нажиматься последовательно или одновременно.

Таблицы стилей автоматически добавят все необходимые связующие символы, такие, как +, между наименованиями клавиш при объединении в <keycombo>.

<para>Чтобы переключиться во второй
    виртуальный терминал, нажмите <keycombo action="simul"><keycap>Alt</keycap>
    <keycap>F1</keycap></keycombo>.</para>

<para>Чтобы выйти из редактора <command>vi</command> без сохранения вашей
  работы, наберите
  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
  <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>Мой оконный менеджер настроен так, что
  <keycombo action="simul"><keycap>Alt</keycap>
    <mousebutton>right</mousebutton>
  </keycombo> кнопка мыши используется для передвижения
  окон.</para>

4.2.5.4. Прикладные программы, команды, параметры и цитаты

Вам часто будет требоваться описать как прикладные программы, так и команды при написании для Руководства. Разница между ними проста: приложение является названием набора (или, возможно, всего лишь 1) программ, которые выполняют конкретную задачу. Команда является названием программы, которую может запустить пользователь.

Кроме того, время от времени вам будет нужно указать один или большее количество параметров, которые может воспринимать команда.

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

Выделяйте имена приложений при помощи <application>.

Когда вы хотите указать команду вместе с разделом ее справочной страницы (что бывает в большинстве случаев), то элемент DocBook называется <citerefentry>. Он будет содержать два элемента, <refentrytitle> и <manvolnum>. Содержимым <refentrytitle> является имя команды, а в <manvolnum> помещается номер раздела справочной страницы.

Это может оказаться громоздким при написании, поэтому для облегчения этой задачи был создан набор сущностей общего назначения. Каждая сущность имеет форму &man.manual-page.manual-section;.

Файлом, в котором содержатся эти сущности, является doc/share/sgml/man-refs.ent, и к нему можно обратиться посредством следующего FPI:

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

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

<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

...

]>

Используйте <command>, когда вы хотите включить название команды ''в строку'', но она должна выглядеть так, как будто её должен набрать пользователь.

Для разметки параметров, которые передаются описываемой команде, используйте <option>.

Когда Вы ссылаетесь к одной команде несколько раз в течение короткого периода времени, то предпочтительно использовать нотацию вида &man.command.sec tion; для разметки первой ссылки и <command> для последующих ссылок. Это делает результат, особенно HTML, гораздо симпатичнее на вид.

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

<para><application>Sendmail</application>
  является наиболее часто используемым почтовым приложением Unix.</para>

<para><application>Sendmail</application> включает программы
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.8; и &man.newaliases.8;.</para>

<para>Один из параметров командной строки для
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, будет выводить текущее состояние
  сообщений в почтовой очереди.  Проверьте это, запустив из командной строки
  <command>sendmail -bp</command>.</para>

4.2.5.5. Файлы, каталоги, расширения

Хотите ли вы указать имя файла, каталог или расширение файла, используйте <filename>.

<para>Исходный код SGML для Руководства на
  английском языке можно найти в каталоге
  <filename>/usr/doc/en/handbook/</filename>.  В этом каталоге первый файл
  называется <filename>handbook.sgml</filename>.  Вы также должны посмотреть на
  <filename>Makefile</filename> и некоторое количество файлов с расширением
  <filename>.ent</filename>.</para>

4.2.5.6. Названия портов

Вам может потребоваться включить в документацию имя программы из Коллекции Портов FreeBSD. Используйте для этого метку <filename> с атрибутом role. Так как порты могут быть установлены в любое место, включайте только категорию и название порта; не включайте сюда /usr/ports.

<para>Установите <filename role="package">net/ethereal</filename> для просмотра сетевого трафика.</para>

4.2.5.7. Устройства

При указания устройства у вас есть два варианта. Вы можете либо указать устройство в том виде, как оно находится в /dev, или вы можете использовать имя устройства так, как оно появляется в ядре. В последнем случае используйте <devicename>.

Иногда у вас нет выбора. Некоторые устройства, такие, как сетевые адаптеры, не имеют соответствий в /dev, или они значительно отличаются от вышеупомянутых.

<para><devicename>sio</devicename> используется
  для коммуникаций по последовательным каналам по FreeBSD.
  <devicename>sio</devicename> доступно через несколько файлов устройств из
  <filename>/dev</filename>, включая <filename>/dev/ttyd0</filename>
  и <filename>/dev/cuaa0</filename>.</para>

<para>В отличие от него, сетевые устройства, такие, как
  <devicename>ed0</devicename>, не присутствуют в <filename>/dev</filename>.</para>

<para>В MS-DOS первый дисковод обозначается как
  <devicename>a:</devicename>.  Во FreeBSD это
  <filename>/dev/fd0</filename>.</para>

4.2.5.8. Хосты, домены, адреса IP и так далее

Вы можете разметить идентификационную информацию для компьютеров, работающих в сети (хостов) несколькими способами, в зависимости от природы информации. Во всех случаях используется элемент </hostid> с атрибутом role, задающим тип размечаемой информации.

<para>Собственно машину всегда можно
  обозначить по имени <hostid>localhost</hostid> с IP-адресом <hostid
  role="ipaddr">127.0.0.1</hostid>.</para>

<para>Домен <hostid role="domainname">FreeBSD.org</hostid> содержит несколько
  различных хостов, включая <hostid role="fqdn">freefall.FreeBSD.org</hostid>
  и <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

<para>При добавлении алиаса IP к интерфейсу (при помощи
  <command>ifconfig</command>) <emphasis>всегда</emphasis> используйте сетевую
  маску <hostid role="netmask">255.255.255.255</hostid> (что может быть
  записано также как <hostid
  role="netmask">0xffffffff</hostid>.</para>

<para>MAC-адрес однозначно идентифицирует любую существующий сетевой адаптер.
  Типичный MAC-адрес выглядит как <hostid
  role="mac">08:00:20:87:ef:d0</hostid>.</para>

4.2.5.9. Имена пользователей

Когда вам нужно указать некоторое имя пользователя, такое, как root или bin, используйте <username>.

<para>Для выполнения большинства функций
  системного администрирования вам нужно быть пользователем
  <username>root</username>.</para>

4.2.5.10. Описание Makefiles

Для описания частей файлов Makefile имеются два элемента, <maketarget> и <makevar>.

<maketarget> идентифицирует цель для построения, экспортируемую из Makefile, которая может быть задана в качестве параметра для make. <makevar> идентифицирует переменную, которая может быть задана (в окружении, в командной строке make или внутри Makefile) для изменения процесса построения.

<para>Двумя распространенными целями в
  <filename>Makefile</filename> являются <maketarget>all</maketarget> и
  <maketarget>clean</maketarget>.</para>

<para>Обычно вызов <maketarget>all</maketarget> приводит к перестроению
  приложения, а вызов <maketarget>clean</maketarget> удаляет временные файлы
  (к примеру, <filename>.o</filename>), созданные в процессе построения.</para>

<para><maketarget>clean</maketarget> может контролироваться несколькими
  переменными, среди которых <makevar>CLOBBER</makevar> и
  <makevar>RECURSE</makevar>.</para>

4.2.5.11. Дословный текст

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

Иногда для разметки такого текста будет достаточно <programlisting>. <programlisting> не всегда подходит, в частности, когда вы хотите включить часть файла ''внутрь'' параграфа.

В таких случаях используйте <literal>.

<para>Строка <literal>maxusers
  10</literal> в файле конфигурации ядра определяет размер многих системных
  таблиц, и примерно задает количество одновременных входов, которые может
  поддерживать система.</para>

4.2.5.12. Выделение пунктов, которые пользователь должен заполнить

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

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

<informalexample>
  <screen>&prompt.user; <userinput>man <replaceable>команда</replaceable></userinput></screen>
</informalexample>

% man команда

<para>Строка <literal>maxusers <replaceable>n</replaceable></literal>
  в файле конфигурации ядра определяет размер многих системных таблиц, и
  примерно задает количество одновременных входов, которое поддерживает
  система.</para>

<para>Для настольной рабочей станции в качестве <replaceable>n</replaceable>
  подойдет значение <literal>32</literal>.</para>

4.2.5.13. Цитирование системных сообщений об ошибках

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

<screen><errorname>Panic: cannot mount root</errorname></screen>

“Panic: cannot mount root”

4.2.6.1. Форматы изображений

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

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

Для точечных изображений, таких, как снимки экранов, используйте формат Portable Network Graphic, и проследите за тем, чтобы файлы с вашими иллюстрациями имели расширение .png.

Это единственные форматы, в которых могут быть изображения, помещаемые в хранилище CVS.

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

4.2.6.2. Разметка

Разметка для изображения сравнительно проста. Сначала разметьте <mediaobject>. <mediaobject> может содержать другие, более специфичные объекты. Мы имеем дело с двумя, <imageobject> и <textobject>.

Вы должны включить один <imageobject> и два элемента <textobject>. <imageobject> будет указывать на имя используемого файла с изображением (без расширения). Элементы <textobject> содержат информацию, которая будет выдаваться пользователю вместе или вместо изображения.

Есть два условия, где это может быть.

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

• Когда читатель смотрит документацию в формате обычного текста. В этом случае каждая иллюстрация должна иметь эквивалент в псевдографике ASCII для выдачи пользователю.

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

<mediaobject>
  <imageobject>
    <imagedata fileref="fig1"> 
  </imageobject>

  <textobject>
    <literallayout class="monospaced">+---------------+ 
|       A       |
+---------------+</literallayout>
  </textobject>

  <textobject>
    <phrase>Рисунок</phrase> 
  </textobject>
</mediaobject>

4.2.6.3. Строки в Makefile

Ваши иллюстрации должны быть перечислены в Makefile в переменной IMAGES. Эта переменная должна содержать имя всех ваших исходных изображений. К примеру, если вы создали три рисунка, fig1.eps, fig2.png и fig3.png, то в вашем Makefile должны быть строки, подобные следующим.

...
IMAGES= fig1.eps fig2.png fig3.png
...

или же

...
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
...

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

4.2.6.4. Изображения и главы в подкаталогах

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

Предположим, что у вас есть книга с тремя главами, причем главы хранятся в своих собственных каталогах, с именами chapter1/chapter.sgml, chapter2/chapter.sgml и chapter3/chapter.sgml. Если в каждой главе есть изображения, связанные с ней, я рекомендую разместить эти иллюстрации в подкаталоге соответствующей главы (chapter1/, chapter2/ и chapter3/).

Однако если вы сделаете так, то должны указать имена каталогов в переменной IMAGES из Makefile и должны указать имя каталога в элементе <imagedata> вашего документа.

Например, если у вас есть chapter1/fig1.png, то chapter1/chapter.sgml должен содержать

<mediaobject>
  <imageobject>
    <imagedata fileref="chapter1/fig1"> 
  </imageobject>

  ...

</mediaobject>

Makefile должен содержать

...
IMAGES=  chapter1/fig1.png
...

Теперь все должно работать.

4.2.7.1. Отсылки на другие части того же самого документа

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

Каждый элемент в DocBook имеет атрибут под названием id. Вы можете разместить текст в этом атрибуте для уникального именования элемента, которому он принадлежит.

Это значение используется, когда вы задаете источник ссылки.

Как правило, вы будете ссылаться на главы или разделы, так что добавляйте атрибут id к этим элементам.

<chapter id="chapter1">
  <title>Введение</title>

  <para>Это введение.  Оно содержит подраздел, который идентифицируется.</para>

  <sect1 id="chapter1-sect1">
    <title>Подраздел 1</title>

    <para>Это подраздел.</para>
  </sect1>
</chapter>

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

Если вы хотите позволить пользователю переходить на конкретный участок документа (возможно, в середине параграфа или примера), то используйте <anchor>. В этом элементе нет содержимого, но может быть атрибут id.

<para>В этом параграфе имеется встроенная
  <anchor id="para1">ссылка на него.  Она не будет показываться в
  документе.</para>

Когда вы хотите предоставить пользователю ссылку, которую можно активировать (чаще всего щелчком) для перехода к разделу документа, имеющему атрибут id, вы можете использовать <xref> либо <link>.

Оба этих элемента имеют атрибут linkend. Значением этого атрибута должно быть значение, которое вы использовали в атрибуте id (не имеет значения, появлялось ли это значение раньше; это работает как для ранее объявленных, так и объявляемых позже ссылок).

Если вы используете <xref>, то вы не управляете текстом ссылки. Он будет для вас сгенерирован.

<para>Дополнительная информация может
  быть найдена в <xref linkend="chapter1">.</para>

<para>Более конкретная информация находится в
  <xref linkend="chapter1-sect1">.</para>

Заметьте, что текст ссылки берется из названия раздела или номера главы.

Если вы хотите управлять текстом ссылки, то используйте <link>. В этот элемент помещается содержимое, которое будет использоваться для ссылки.

<para>Дополнительная информация может быть
  найдена в <link linkend="chapter1">первой главе</link>.</para>

<para>Более конкретная информация находится в <link
  linkend="chapter1-sect1">этом</link> разделе.</para>

4.2.7.2. Ссылки на документы в WWW

Отсылки на внешние документы гораздо проще, если вы знаете URL документа, на который хотите сослаться. Используйте <ulink>. Атрибут url представляет собой URL страницы, на которую указывает ссылка, а содержимым элемента является текст, выдаваемый пользователю для активации ссылки.

<para>Конечно, вы можете прекратить чтение
  этого документа и перейти на <ulink url="&url.base;/ru/index.html">домашнюю
  страницу FreeBSD</ulink>.</para>