4.2 DocBook

4.2.3.1 Започване на книга

Съдържанието на книга се съдържа в <book> елемент. Поради това, че той съдържа и структурното маркиране, може да се включат и допълнителни елементи с информация за книгата. Това може да е или мета информация или допълнително съдържание използвано за генериране на заглавната страница.

Тази допълнителна информация трябва да се бъде включена в <bookinfo>.

<book>
  <bookinfo>
    <title>Your title here</title>
    
    <author>
      <firstname>Your first name</firstname>
      <surname>Your surname</surname>
      <affiliation>
        <address><email>Your e-mail address</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your e-mail address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the book's contents here.</para>
    </abstract>
  </bookinfo>

  ...

</book>

4.2.3.2 Започване на статия

Съдържанието на статия се съдържа в <article> елемент. Както и структурните елементи този елемент може да съдържа допълнителни елементи за статията. Това може да е или мета информация или допълнително съдържание използвано за генериране на заглавна страница.

Тази допълнителна информация трябва да се постави в <articleinfo>.

<article>
  <articleinfo>
    <title>Your title here</title>
    
    <author>
      <firstname>Your first name</firstname>
      <surname>Your surname</surname>
      <affiliation>
        <address><email>Your e-mail address</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your e-mail address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the article's contents here.</para>
    </abstract>
  </articleinfo>

  ...

</article>

4.2.3.3 Означаване на глави

Използвайте <chapter> за да маркирате главите. Всяка глава задължително съдържа <title>. Статиите не съдържат глави, те са запазени за книгите.

<chapter>
  <title>The chapter's title</title>

  ...
</chapter>

Глава не може да бъде без съдържание, трябва да съдържа и други елементи освен <title>. Ако е необходимо да включите празна глава, използвайте празен параграф.

<chapter>
  <title>This is an empty chapter</title>

  <para></para>
</chapter>

4.2.3.4 Подсекции на главите

В книга, главите могат (но не е задължително) да бъдат разбити на секции, подсекции и т.н. В статиите, секциите са основният структурен елемент и всяка статия трябва да съдържа поне една. Използва се <sectn> елемент. Където n означава номера на секция, което идентифицира ниво на секцията.

Първата <sectn> е <sect1>. Можете да имате една или повече от тези в глава. Те може да съдържат един или повече <sect2> елементи и т.н. до <sect5>.

<chapter>
  <title>A sample chapter</title>

  <para>Some text in the chapter.</para>

  <sect1>
    <title>First section (1.1)</title>

    ...
  </sect1>

  <sect1>
    <title>Second section (1.2)</title>

    <sect2>
      <title>First sub-section (1.2.1)</title>

      <sect3>
        <title>First sub-sub-section (1.2.1.1)</title>

        ...
      </sect3>
    </sect2>

    <sect2>
      <title>Second sub-section (1.2.2)</title>

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

4.2.3.5 Подразделяне с помощта на <part>

Можете да добавите още един слой на организация между <book> и <chapter> с помощта на <part>. Това не може да се прави в <article>.

<part>
  <title>Introduction</title>

  <chapter>
    <title>Overview</title>

    ...
  </chapter>

  <chapter>
    <title>What is FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>History</title>

    ...
  </chapter>
</part>

4.2.4.1 Параграфи

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

През повечето време ще се налага да използвате само <para>. <formalpara> включва <title> елемент, а <simpara> забранява някои елементи в <para>. Използвайте <para>.

<para>This is a paragraph.  It can contain just about any
  other element.</para>

4.2.4.2 Блокови цитати

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

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

<para>A small excerpt from the US Constitution;</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 Съвети, бележки, предупреждения, опасности, важна информация и отметки.

Може да се наложи да включите допълнителна информация, отделно от главното тяло на текста. Обикновенно, това е ``meta'' информация, която потребителят трябва да има в предвид.

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

Все пак, не е много ясно кога кой елемент да се използва. DocBook документацията препоръчва следното;

• Бележка се използва, когато информацията трябва да бъде взета под внимание от всички потребители.

• Важно е елемент, който се поставя като вариация на Бележка.

• Внимание служи за предпазване от евентуална загуба на информация или повреда на програма (ОС).

• Предупреждение за информация относно възможна повреда на хардуер или опасност за живота или крайници.

<warning>
  <para>Installing FreeBSD may make you want to delete Windows from your
    hard disk.</para>
</warning>

4.2.4.4 Списъци и процедури

Често ще ви се налага да покажете списък с информация на потребителя или да представите стъпки, които трябва да се изпълнят за да се постигне определена цел.

За да постигнете това използвайте <itemizedlist>, <orderedlist> или <procedure>[1]

<itemizedlist> и <orderedlist> са подобни на техните съответстващи в HTML, <ul> и <ol>. Всеки от тях се състои от един или повече <listitem> елементи и всеки <listitem> съдържа един или повече блокови елементи. <listitem> елементите са аналогични на HTML <li>. Все пак за разлика от HTML те са задължителни.

<procedure> е леко различен. Състои се от <step> (стъпки), които от своя страна се състоят от други <step> или <substep>. Всеки <step> съдържа блокови елементи.

<itemizedlist>
  <listitem>
    <para>This is the first itemized item.</para>
  </listitem>

  <listitem>
    <para>This is the second itemized item.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>This is the first ordered item.</para>
  </listitem>

  <listitem>
    <para>This is the second ordered item.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Do this.</para>
  </step>

  <step>
    <para>Then do this.</para>
  </step>

  <step>
    <para>And now do this.</para>
  </step>
</procedure>

4.2.4.5 Представяне на примерни файлове

Ако е необходимо да покажете фрагмент от файл (или целия файл) на потребителя, пакетирайте го в <programlisting> елемент.

Празните интервали и новите редове в <programlisting> са значещи. Това значи, че началния етикет трябва да бъде на един ред с първият ред от фрагмента, а затварящият етикет трябва да бъде на един ред с последния. В противен случай могат да се появят фалшиви празни редове.

<para>When you have finished, your program should look like
  this;</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 Извиквания (Callouts)

Извикванията са механизъм за обръщане към по-предишна част от текст или специфично място в предишен пример без всъщност да има препратка в текущият текст.

За да направите това, маркирайте зона в част от ваш пример (<programlisting>, <literallayout> или каквото и да е) с <co> елемент. Всеки елемент трябва да има уникално id. След примера ви, включете <calloutlist> който се обръща към примера и предоставя допълнителен коментар.

<para>When you have finished, your program should look like
  this;</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>Includes the standard IO header file.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Specifies that <function>main()</function> returns an
      int.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>The <function>printf()</function> call that writes
      <literal>hello, world</literal> to standard output.</para>
  </callout>
</calloutlist>

#include <stdio.h> 

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

4.2.4.7 Таблици

За разлика от HTML, не е необходимо да използвате таблици за разполагане на нещата т.като stylesheet прави това. Използвайте таблици само при маркиране на табулирани данни.

В основни термини (вижте документацията на DocBook за повече детайли) всяка таблица (която може да бъде formal или informal) се състои от <table> елемент. Той съдържа поне един <tgroup> елемент, който задава (като атрибут) броя колони за таблична група. В таблична група може да има един <thead> елемент съдържащ заглавията на таблицата (колоните) и един <tbody>, който съдържа тялото на таблицата.

И двата <tgroup> и <thead> съдържат <row> елементи, съдържащи <entry> елементи. Всеки <entry> елемент задава една клетка в таблицата.

<informaltable>
  <tgroup cols="2">
    <thead>
      <row>
        <entry>This is column head 1</entry>
        <entry>This is column head 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>Row 1, column 1</entry>
        <entry>Row 1, column 2</entry>
      </row>

      <row>
        <entry>Row 2, column 1</entry>
        <entry>Row 2, column 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

Ако не желаете контур около таблицата, frame атрибут може да бъде добавен към <informaltable> елемент със стойност 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>However, make sure that the search does not go beyond the
  <quote>boundary between local and public administration</quote>,
  as RFC 1535 calls it.</para>

4.2.5.3 Клавиши, бутони на мишка и комбинации

За да обозначите определен клавиш на клавиатурата използвайте <keycap>. При обозначаване на бутон на мишка <mousebutton>. За клавишни комбинации или специфично използване на мишката - пакетирайте в <keycombo>.

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

stylesheets автоматично добавят свързващите символи, като + между имената на клавишите, когато се използва <keycombo>.

<para>To switch to the second virtual terminal, press 
  <keycombo action="simul"><keycap>Alt</keycap>
    <keycap>F1</keycap></keycombo>.</para>

<para>To exit <command>vi</command> without saving your work, type
  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
    <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>My window manager is configured so that
  <keycombo action="simul"><keycap>Alt</keycap>
    <mousebutton>right</mousebutton>
  </keycombo> mouse button is used to move windows.</para>

4.2.5.4 Приложения, команди, опции или сайтове

Често ще ви се налага да споменавате приложения и команди, когато пишете за Handbook (Ръководството). Разликата между тях е проста: приложение е името на пакет (или само 1) програми, които служат за изпълнението на определена задача. Команда е името на програма, която потребителя може да стартира.

В допълнение вероятно ще ви се иска да покажете една или повече опции, които командата може да получи.

Най-накрая, почти сигурно, ще ви се наложи да покажете команда с нейния номер на секция от помощните ръководства във формат на ``command(number)'', който често се използва в 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> за да маркирате опция към команда.

Това може да е малко объркващо и понякога кое да се избере не е много ясно. Да се надяваме, че следният пример ще поясни.

<para><application>Sendmail</application> is the most
  widely used Unix mail application.</para>

<para><application>Sendmail</application> includes the
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.8;, and &man.newaliases.8;
  programs.</para>

<para>One of the command line parameters to <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, will display the current
  status of messages in the mail queue.  Check this on the command
  line by running <command>sendmail -bp</command>.</para>

4.2.5.5 Файлове, директории и разширения

Когато е необходимо да опишете име на файл, директория или файлово разширение, използвайте <filename>.

<para>The SGML source for the Handbook in English can be
  found in <filename>/usr/doc/en/handbook/</filename>.  The first
  file is called <filename>handbook.sgml</filename> in that
  directory.  You should also see a <filename>Makefile</filename>
  and a number of files with a <filename>.ent</filename>
  extension.</para>

4.2.5.6 Имена на портове

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

<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>

4.2.5.7 Устройства

Когато споменавате устройства имате два избора. Можете да ги споменавате както са в /dev или можете да използвате имената на устройствата както са в ядрото (kernel). В последния случай използвайте <devicename>.

Понякога нямате избор. Някои устройства, като мрежови карти, нямат съответствия в /dev или те са различни.

<para><devicename>sio</devicename> is used for serial
  communication in FreeBSD.  <devicename>sio</devicename> manifests
  through a number of entries in <filename>/dev</filename>, including
  <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>

<para>By contrast, the networking devices, such as
  <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.

<para>In MS-DOS, the first floppy drive is referred to as
  <devicename>a:</devicename>.  In FreeBSD it is
  <filename>/dev/fd0</filename>.</para>

4.2.5.8 Сървъри, домейни, IP адреси и т.н.

Можете да маркирате информация за мрежови компютри (сървъри) по различни начини в зависимост от естеството на информацията. Използвайте <hostid> като елемент с role атрибут указващ типа на маркираната информация.

<para>The local machine can always be referred to by the
  name <hostid>localhost</hostid>, which will have the IP address
  <hostid role="ipaddr">127.0.0.1</hostid>.</para>

<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
  contains a number of different hosts, including
  <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
  <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

<para>When adding an IP alias to an interface (using
  <command>ifconfig</command>) <emphasis>always</emphasis> use a
  netmask of <hostid role="netmask">255.255.255.255</hostid>
  (which can also be expressed as <hostid
    role="netmask">0xffffffff</hostid>.</para>

<para>The MAC address uniquely identifies every network card
  in existence.  A typical MAC address looks like <hostid
    role="mac">08:00:20:87:ef:d0</hostid>.</para>

4.2.5.9 Потребителски имена

Когато трябва да споменете специфично потребителско име, като root или bin използвайте <username>.

<para>To carry out most system administration functions you
  will need to be <username>root</username>.</para>

4.2.5.10 Описания на Makefile-ове

Съществуват два елемента за описване на части от Makefile-ове, <maketarget> и <makevar>.

<maketarget> задава целта за компилиране от Makefile, която може да бъде зададена като параметър на make. <makevar> задава променлива, която може да бъде инициализирана (в обкръжението, от make командата линия или от самия Makefile).

<para>Two common targets in a <filename>Makefile</filename>
  are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>

<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
  application, and invoking <maketarget>clean</maketarget> will remove
  the temporary files (<filename>.o</filename> for example) created by
  the build process.</para>

<para><maketarget>clean</maketarget> may be controlled by a number of
  variables, including <makevar>CLOBBER</makevar> and
  <makevar>RECURSE</makevar>.</para>

4.2.5.11 Дословен текст

Често ще ви се налага да включвате ``дословен'' текст в Ръководството (Наръчника). Това е текст, който е изваден от друг файл, или трябва да бъде копиран от Ръководството в друг файл дословно.

Понякога <programlisting> ще бъде достатъчно за да обозначите този тип текст. <programlisting> не винаги е подходящ, особено когато искате да включите част от файл ``на реда'' с останалата част от параграфа.

В тези случаи използвайте <literal>.

<para>The <literal>maxusers 10</literal> line in the kernel
  configuration file determines the size of many system tables, and is
  a rough guide to how many simultaneous logins the system will
  support.</para>

4.2.5.12 Изобразяване на неща, който потребителят трябва да въведе

Може да се наложи да покажете на потребителят какво трябва да направи, да въведе във файл или на командната линия, където обаче потребителят не може просто да копира примерите, които сте предоставили а вместо това трябва сам да добави информация.

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

<informalexample>
  <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>

% man command

<para>The <literal>maxusers <replaceable>n</replaceable></literal>
  line in the kernel configuration file determines the size of many system
  tables, and is a rough guide to how many simultaneous logins the system will
  support.</para>

<para>For a desktop workstation, <literal>32</literal> is a good value
  for <replaceable>n</replaceable>.</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, което искате да включите в документ. Изображението е на правоъгълник с едно А в средата. Маркирането би било следното.

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

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

  <textobject>
    <phrase>A picture</phrase> 
  </textobject>
</mediaobject>

4.2.6.3 Makefile команди

Вашите изображения трябва да бъдат описани в Makefile в IMAGES променлива. Тази променлива трябва да съдържа имената на всички ваши графични файлове. На пример, ако имате три фигури, fig1.eps, fig2.png, fig3.png, тогава Makefile-а ще съдържа подобни на тези редове .

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

or

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

Отново Makefile ще изработи пълния списък на изображенията, които са необходими за компилирането на документа, вие трябва просто да ги опишете.

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

Трябва да бъдете внимателни когато разделяте документацията на по-малки файлове (вижте Section 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>Introduction</title>

  <para>This is the introduction.  It contains a subsection,
    which is identified as well.</para>

  <sect1 id="chapter1-sect1">
    <title>Sub-sect 1</title>

    <para>This is the subsection.</para>
  </sect1>
</chapter>

Разбира се трябва да използвате по-описателни стойности. Те трябва да бъдат уникални в документа (т.е. не само името на файла, но и документа може да бъде включен). Забележете как id на подсекция се конструира чрез добавянето на текст към id на главата. Това ще осигури уникалността им.

Ако искате да позволите на потребителят да скочи в специфична секция на документа (вероятно в средата на параграф или пример), използвайте <anchor>. Този елемент няма съдържание, но приема id атрибут.

<para>This paragraph has an embedded
  <anchor id="para1">link target in it.  It will not show up in
  the document.</para>

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

И двата елемента имат linkend атрибут. Стойността на този атрибут трябва да бъде тази, която сте използвали като id атрибут (няма значение дали стойността му все още не се е появила в документа; това ще работи както за препратки напред, така и назад).

Ако използвате <xref> тогава нямате контрол върху текста на препратката. Той ще бъде генериран автоматично.

<para>More information can be found
  in <xref linkend="chapter1">.</para>

<para>More specific information can be found
  in <xref linkend="chapter1-sect1">.</para>

Обърнете внимание как текста на препратката се образува от името на секцията или номера на главата.

Ако искате да контролирате текста на препратката използвайте <link>. Този елемент опакова съдържание и то ще бъде използвано за препратката.

<para>More information can be found in
  <link linkend="chapter1">the first chapter</link>.</para>

<para>More specific information can be found in
  <link linkend="chapter1-sect1">this</link> section.</para>

4.2.7.2 Препращане към документ от WWW

Препращането към външен документ е доста по-лесно, т.като знаете URL на документа към който искате да препратите. Използвайте <ulink>. url атрибута е адреса на страницата към която препратката сочи, а съдържанието на елемента е текста, който ще бъде показан на потребителя за активиране на препратката.

<para>Of course, you could stop reading this document and
  go to the <ulink url="../../../../index.html">FreeBSD
  home page</ulink> instead.</para>