<!--
     The FreeBSD Russian Documentation Project

     $FreeBSD$
     $FreeBSDru: frdp/doc/ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.sgml,v 1.7 2005/05/06 19:12:59 andy Exp $

     Original revision: 1.69
-->

<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
	 copyright notice, this list of conditions and the following
	 disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
	 converted to PDF, PostScript, RTF and other formats) must reproduce
	 the above copyright notice, this list of conditions and the
	 following disclaimer in the documentation and/or other materials
	 provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="sgml-markup">
  <title>Разметка SGML</title>

  <para>В этой главе описываются два языка разметки, с которыми вы можете
    встретиться, когда принимаете участие в Проекте Документирования FreeBSD.
    Каждый раздел описывает язык разметки и подробно касается разметки, которую
    вы, вероятнее всего, будете использовать или которая уже
    используется.</para>

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

  <para>Это <emphasis>не</emphasis> исчерпывающий список элементов, так как это
    стало бы простым повторением документации по каждому языку.  Предназначение
    этого раздела заключается в перечислении тех элементов, которые в первую
    очередь будут полезными для вас.  Если у вас есть вопрос по поводу
    наилучшей разметки конкретного текста, пожалуйста, пошлите его по адресу
    &a.doc;</para>

  <note>
    <title>Строчный или блочный</title>

    <para>Во всем документе при описании элементов
      <emphasis>строчный</emphasis> означает, что элемент может появиться в
      блочном элементе, и не приводит к концу строки.
      <emphasis>Блочный</emphasis> элемент, по сравнению с этим, приводит к
      завершению строки (и другой обработке) при его появлении.</para>
  </note>

  <sect1 id="sgml-markup-html">
    <title>HTML</title>

    <para>HTML, HyperText Markup Language (Язык Гипертекстовой Разметки),
      применяется в World Wide Web.  Более полная информация может быть найдена
      по адресу &lt;URL:<ulink url="http://www.w3.org/"></ulink>&gt;.</para>

    <para>HTML применяется для разметки страниц на веб-сервере FreeBSD.  Он не
      применяется (как правило) для разметки другой документации, так как
      DocBook предоставляет на выбор гораздо более богатый набор элементов.
      Соответственно, обычно вы встречаетесь только со страницами HTML, если вы
      пишете для веб-сайта.</para>

    <para>HTML прошел через последовательность версий, 1, 2, 3.0, 3.2 и самую
      последнюю, 4.0 (которая есть как в <emphasis>строгом</emphasis>, так и
      <emphasis>нежестком</emphasis> вариантах).</para>

    <para>DTD для HTML доступны из коллекции портов через порт
      <filename role="package">textproc/html</filename>.  Они автоматически
      устанавливаются как часть порта <filename
      role="package">textproc/docproj</filename>.</para>

    <sect2>
      <title>Формальный Публичный Идентификатор (Formal Public
	Identifier - FPI)</title>

      <para>Существует несколько FPI для HTML, зависящих от версии (также
	называемой уровнем) HTML, которому вы хотите объявить, что ваш документ
	соответствует.</para>

      <para>Основная масса документов HTML на веб-сайте FreeBSD соответствует
	простой версии HTML 4.0.</para>

      <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
    </sect2>

    <sect2>
      <title>Элементы разделов</title>

      <para>Документ HTML обычно делится на два раздела.  Первый раздел,
	называемый <emphasis>заголовком</emphasis> (head), содержит
	мета-информацию о документе, такую, как его название, имя автора,
	родительский документ и так далее.  Второй раздел,
	<emphasis>тело</emphasis> (body), включает содержимое, которое будет
	выводиться пользователю.</para>

      <para>Эти разделы помечаются элементами <sgmltag>head</sgmltag> и
	<sgmltag>body</sgmltag> соответственно.  Эти элементы размещаются
	внутри элемента <sgmltag>html</sgmltag> самого верхнего уровня.</para>

      <example>
	<title>Обычная структура документа HTML</title>

	<programlisting>&lt;html>
  &lt;head>
	  &lt;title><replaceable>Заголовок документа</replaceable>&lt;/title>
  &lt;/head>

  &lt;body>

    &hellip;

  &lt;/body>
&lt;/html></programlisting>
      </example>
    </sect2>

    <sect2>
      <title>Блочные элементы</title>

      <sect3>
	<title>Заголовки</title>

	<para>HTML позволяет вам выделять заголовки в вашем документе до шести
	  различных уровней.</para>

	<para>Самым большим и наиболее бросающимся в глаза заголовком является
	  <sgmltag>h1</sgmltag>, затем <sgmltag>h2</sgmltag>, продолжая до
	  нисходящей до <sgmltag>h6</sgmltag>.</para>

	<para>Элемент содержит текст заголовка.</para>

	<example>
	  <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag> и так
	    далее.</title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<h1>First section</h1>

<!-- Здесь помещается введение документа -->

<h2>Это заголовок первого раздела</h2>

<!-- Здесь размещается содержимое первого раздела -->

<h3>Это заголовок первого подраздела</h3>

<!-- Здесь размещается содержимое первого подраздела -->

<h2>Это заголовок второго раздела</h2>

<!-- Здесь размещается содержимое второго раздела -->]]></programlisting>
	</example>

	<para>Вообще говоря, на странице HTML должен иметься один заголовок
	  первого уровня (<sgmltag>h1</sgmltag>).  Он может содержать много
	  заголовков второго уровня (<sgmltag>h2</sgmltag>), которые, в свою
	  очередь, содержат много заголовков третьего уровня.  Каждый элемент
	  <sgmltag>h<replaceable>n</replaceable></sgmltag> должен иметь тот же
	  самый элемент, но выше по иерархии.  Избегайте пропусков в
	  нумерации.</para>

	<example>
	  <title>Неправильный порядок следования элементов
	    <sgmltag>h<replaceable>n</replaceable></sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<h1>Первый раздел</h1>

<!-- Введение документа -->

<h3>Подраздел</h3>

<!-- Это плохо, пропущен <h2> -->]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Параграфы</title>

	<para>HTML поддерживает элемент отдельного параграфа,
	  <sgmltag>p</sgmltag>.</para>

	<example>
	  <title><sgmltag>p</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Это параграф.  Он может содержать
практически любой другой элемент.</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Цитирование блока</title>

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

	<example>
	  <title><sgmltag>blockquote</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Короткий отрывок из Конституции США:</p>

<blockquote>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.</blockquote>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Списки</title>

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

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

	<para>Упорядоченные списки помечаются элементом <sgmltag>ol</sgmltag>,
	  неупорядоченные элементом <sgmltag>ul</sgmltag>, а списки определений
	  элементом <sgmltag>dl</sgmltag>.</para>

	<para>Упорядоченные и неупорядоченные списки содержат элементы списка,
	  отмечаемые элементом <sgmltag>li</sgmltag>.  Элемент списка может
	  содержать текст или может разбиваться на один или большее количество
	  элементов <sgmltag>p</sgmltag>.</para>

	<para>Списки определений содержат определяемые термины
	  (<sgmltag>dt</sgmltag>) и собственно определения
	  (<sgmltag>dd</sgmltag>).  Определяемый термин может содержать только
	  строчные элементы.  Определение может содержать другие блочные
	  элементы.</para>

	<example>
	  <title><sgmltag>ul</sgmltag> и <sgmltag>ol</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Неупорядоченный список.  Элементам
списка должны предшествовать маркеры.</p>

<ul>
  <li>Первый элемент</li>

  <li>Второй элемент</li>

  <li>Третий элемент</li>
</ul>

<p>Упорядоченный список, с элементами, состоящими из нескольких параграфов.
  Каждый элемент (замечание: но не каждый параграф) будет пронумерован.</p>

<ol>
  <li><p>Это первый элемент.  В нем только один параграф.</p></li>

  <li><p>Это первый параграф второго элемента.</p>

    <p>Это второй параграф второго элемента.</p></li>

  <li><p>Это первый и единственный параграф третьего элемента списка.</p></li>
</ol>]]></programlisting>
	</example>

	<example>
	  <title>Списки определений с <sgmltag>dl</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<dl>
  <dt>Термин 1</dt>

  <dd><p>Параграф 1 определения 1.</p>

    <p>Параграф 2 определения 1.</p></dd>

  <dt>Термин 2</dt>

  <dd><p>Параграф 1 определения 2.</p></dd>

  <dt>Термин 3</dt>

  <dd>Параграф 1 определения 3.  Заметьте, что элемент &lt;p&gt;
    в случае единственного параграфа не нужен.</dd>
</dl>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Предварительно отформатированный текст</title>

	<para>Вы можете указать, что текст должен быть показан пользователю
	  точно в таком виде, как вы его набрали в файле.  Обычно это значит,
	  что текст будет выводиться шрифтом фиксированного размера, несколько
	  пробелов не будут объединяться в один и символы окончания строк
	  принимаются во внимание.</para>

	<para>Для этого поместите содержимое в элемент
	  <sgmltag>pre</sgmltag>.</para>

	<example>
	  <title><sgmltag>pre</sgmltag></title>

	  <para>Вы можете использовать <sgmltag>pre</sgmltag> для разметки
	    сообщения электронной почты;</para>

	  <programlisting><![ CDATA [<pre>  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: New documentation available

  There's a new copy of my primer for contributers to the FreeBSD
  Documentation Project available at

    <URL:http://people.FreeBSD.org/~nik/primer/index.html>

  Comments appreciated.

  N</pre>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Таблицы</title>

	<note>
	  <para>Большинство браузеров, работающих в текстовом режиме (таких,
	    как Lynx), не выводят таблицы достаточно правильно.  Если вы
	    рассчитываете на табличный вывод вашего текста, то во избежание
	    путаницы вы должны использовать альтернативную разметку.</para>
	</note>

	<para>Размечайте табличную информацию при помощи элемента
	  <sgmltag>table</sgmltag>.  Таблица состоит из одной или большего
	  количества строк (<sgmltag>tr</sgmltag>), каждая из которых содержит
	  одну или большее количество ячеек с данными (<sgmltag>td</sgmltag>).
	  Каждая ячейка может содержать другие блочные элементы, такие, как
	  параграфы или списки.  Она может также содержать другую таблицу
	  (такое вложение может быть бесконечным).  Если ячейка содержит только
	  один параграф, то вам не нужно включать элемент
	  <sgmltag>p</sgmltag>.</para>

	<example>
	  <title>Простое использование <sgmltag>table</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Это простая таблица 2x2.</p>

<table>
  <tr>
    <td>Верхняя левая ячейка</td>

    <td>Верхняя правая ячейка</td>
  </tr>

  <tr>
    <td>Нижняя левая ячейка</td>

    <td>Нижняя правая ячейка</td>
  </tr>
</table>]]></programlisting></example>

	<para>Ячейка может занимать несколько строк и столбцов.  Для указания
	  этого добавьте атрибуты <literal>rowspan</literal> и/или
	  <literal>colspan</literal> со значениями, указывающими количество
	  строк или столбцов, которые должны быть заняты.</para>

	<example>
	  <title>Использование <literal>rowspan</literal></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Одна высокая тонкая ячейка слева,
  две низкие ячейки за ней справа.</p>

<table>
  <tr>
    <td rowspan="2">Длинная и высокая</td>
  </tr>

  <tr>
    <td>Верхняя ячейка</td>

    <td>Нижняя ячейка</td>
  </tr>
</table>]]></programlisting>
	</example>

	<example>
	  <title>Использование <literal>colspan</literal></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Одна длинная ячейка сверху, две
  короткие ячейки под ней.</p>

<table>
  <tr>
    <td colspan="2">Верхняя ячейка</td>
  </tr>

  <tr>
    <td>Нижняя левая ячейка</td>

    <td>Нижняя правая ячейка</td>
  </tr>
</table>]]></programlisting>
	</example>

	<example>
	  <title>Использование <literal>rowspan</literal> и
	    <literal>colspan</literal> одновременно</title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>На сетке 3x3 верхний левый блок является
  набором клеток 2x2, объединенных в одну ячейку.
  Остальные клетки нормальные.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Верхняя левая большая ячейка</td>

    <td>Верхняя правая клетка</td>
  </tr>

  <tr>
    <!-- Из-за того, что большая ячейка слева объединяется в
	 эту строку, первый <td> появится справа -->

    <td>Средняя правая ячейка</td>
  </tr>

  <tr>
    <td>Нижняя левая ячейка</td>

    <td>Нижняя средняя ячейка</td>

    <td>Нижняя правая ячейка</td>
  </tr>
</table>]]></programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Строчные элементы</title>

      <sect3>
	<title>Выделяющая информация</title>

	<para>В HTML имеется два уровня выделения, <sgmltag>em</sgmltag> и
	  <sgmltag>strong</sgmltag>.  <sgmltag>em</sgmltag> предназначен для
	  обычного уровня выделения, а <sgmltag>strong</sgmltag> указывает на
	  более сильное выделение.</para>

	<para>Как правило, <sgmltag>em</sgmltag> выводится наклонным, а
	  <sgmltag>strong</sgmltag> жирным шрифтами.  Это не всегда так, и вам
	  не следует на это полагаться.</para>

	<example>
	  <title><sgmltag>em</sgmltag> и <sgmltag>strong</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p><em>Этот текст</em> выделен, а
  <strong>этот текст</strong> выделен сильно.</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Жирный и наклонный</title>

	<para>Так как в HTML имеется презентационная разметка, вы можете также
	  указать, что указанное содержимое должно быть выведено жирным или
	  наклонным шрифтами.  Это элементы <sgmltag>b</sgmltag> и
	  <sgmltag>i</sgmltag> соответственно.</para>

	<example>
	  <title><sgmltag>b</sgmltag> и <sgmltag>i</sgmltag></title>

	  <programlisting><![ CDATA [<p><b>Этот текст</b> выводится жирным, а
  <i>этот текст</i> выводится наклонным шрифтами.</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Указание текста одинаковой ширины</title>

	<para>Если у вас есть текст, который должен быть выведен моноширинным
	  шрифтом (шрифтом пишущей машинки), используйте <sgmltag>tt</sgmltag>
	  (от слова <quote>teletype</quote> - телетайп).</para>

	<example>
	  <title><sgmltag>tt</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Этот документ первоначально создал
  Ник Клэйтон (Nik Clayton), которому можно написать по электронной почте
на адрес <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Размер текста</title>

	<para>Вы можете указать, что содержимое должно показываться шрифтами
	  большего или меньшего размеров.  Есть три способа сделать это.</para>

	<orderedlist>
	  <listitem>
	    <para>Используйте <sgmltag>big</sgmltag> и <sgmltag>small</sgmltag>
	      вокруг содержимого, размер которого вы хотите изменить.  Эти
	      метки могут быть вложенными, так, возможно выводить
	      <literal>&lt;big&gt;&lt;big&gt;этот текст гораздо
	      крупнее&lt;/big&gt;&lt;/big&gt;</literal>.</para>
	  </listitem>

	  <listitem>
	    <para>Используйте набор <sgmltag>font</sgmltag> совместно с
	      атрибутом <literal>size</literal>, установленным в
	      <literal>+1</literal> или <literal>-1</literal> соответственно.
	      Это будет иметь тот же самый эффект, что и использование
	      <sgmltag>big</sgmltag> или <sgmltag>small</sgmltag>.  Однако
	      такое использование не рекомендуется.</para>
	  </listitem>

	  <listitem>
	    <para>Использование <sgmltag>font</sgmltag> вместе с атрибутом
	      <literal>size</literal>, установленным в значение от 1 до 7.
	      Размер шрифта, используемый по умолчанию, равен
	      <literal>3</literal>.  Это подход не рекомендуется.</para>
	  </listitem>
	</orderedlist>

	<example>
	  <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag> и
	    <sgmltag>font</sgmltag></title>

	  <para>В следующих фрагментах выполняется одно и тоже.</para>

	  <programlisting><![ CDATA [<p>Этот текст <small>немного меньше</small>.  А
  этот текст <big>немножко больше</big>.</p>

<p>Этот текст <font size="-1">несколько меньше</font>.  А
  этот  текст <font size="+1">немного крупнее</font.</p>

<p>Этот текст <font size="2">немного мельче</font>.  А
  этот текст <font size="4">немного крупнее</font>.</p>]]></programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Ссылки</title>

      <note>
	<para>Ссылки также являются внутристрочными элементами.</para>
      </note>

      <sect3>
	<title>Ссылки на другие документы на WWW</title>

	<para>Для того, чтобы включить ссылку на другой документ из Интернет,
	  вы должны знать URL документа, на который хотите сослаться.</para>

	<para>Ссылка выделяется элементом <sgmltag>a</sgmltag> и атрибутом
	  <literal>href</literal>, содержащим URL целевого документа.
	  Содержимое элемента заменяет ссылку и обычно каким-то способом
	  выводится пользователю (подчеркиванием, изменением цвета, другим
	  типом курсора мыши, находящимся над ссылкой, и так далее).</para>

	<example>
	  <title>Использование <literal>&lt;a href="..."&gt;</literal></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p>Дополнительная информация находится на
  <a href="http://www.FreeBSD.org/">веб-сайте FreeBSD</a>.</p>]]></programlisting>
	</example>

	<para>Эти ссылки направят пользователя к началу выбранного
	  документа.</para>
      </sect3>

      <sect3>
	<title>Ссылки на другие части документов</title>

	<para>Ссылка на точку внутри другого документа (или внутри того же
	  самого документа) требует, чтобы автор документа включил метку, на
	  которую вы можете сослаться.</para>

	<para>Метки помечаются с помощью <sgmltag>a</sgmltag> и атрибута
	  <literal>name</literal> вместо <literal>href</literal>.</para>

	<example>
	  <title>Использование <literal>&lt;a name="..."&gt;</literal></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<p><a name="para1">На</a> этот параграф
  можно сослаться из других мест
  по имени <tt>para1</tt>.</p>]]></programlisting>
	</example>

	<para>Чтобы сослаться на именованную часть документа, напишите обычную
	  ссылку на тот документ, но включите имя метки после символа
	  <literal>#</literal>.</para>

	<example>
	  <title>Ссылка на именованную часть другого документа</title>

	  <para>Предположим, что пример с <literal>para1</literal> расположен в
	    документе с именем <filename>foo.html</filename>.</para>

	  <programlisting><![ CDATA [<p>Дополнительная информация может быть
  найдена в <a href="foo.html#para1">первом абзаце</a> из
  <tt>foo.html</tt>.</p>]]></programlisting>
	</example>

	<para>если вы ссылаетесь на именованную метку внутри того же самого
	  документа, то вы можете опустить URL документа, и просто включить
	  имя метки (с предшествующим <literal>#</literal>).</para>

	<example>
	  <title>Ссылка на именованную часть того же самого документа</title>

	  <para>Положим, что пример с <literal>para1</literal> расположен в
	    этом документе</para>

	  <programlisting><![ CDATA [<p>Дополнительная информация может быть
  найдена в <a href="#para1">первом абзаце</a> этого
  документа.</p>]]></programlisting>
	</example>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="sgml-markup-docbook">
    <title>DocBook</title>

    <para>DocBook был разработан компаниями HaL Computer Systems и O'Reilly
      &amp; Associates, как DTD для написания технической документации
      <footnote><para>Краткая история находится по адресу <ulink
      url="http://www.oasis-open.org/committees/docbook/intro.shtml">
      http://www.oasis-open.org/committees/docbook/intro.shtml</ulink>.
      </para></footnote>.  С 1998 года его поддержкой занимается <ulink
      url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
      DocBook Technical Committee</ulink>.  Поэтому, и в отличие от
      LinuxDoc и HTML, DocBook очень сильно ориентирован на разметку,
      описывающую <emphasis>что</emphasis> это, а не на описание того,
      <emphasis>как</emphasis> это должно выглядеть.</para>

    <note>
      <title><literal>Формально</literal> или
	<literal>неформально</literal></title>

      <para>Некоторые элементы могут существовать в двух формах,
	<emphasis>formal</emphasis> и <emphasis>неформальной</emphasis>.
	Обычно формальная версия элемента будет состоять из заголовка, за
	которым следует информация о версии элемента.  Неформальная форма
	заголовка не содержит.</para>
    </note>

    <para>DocBook DTD находится в коллекции портов как порт
      <filename role="package">textproc/docbook</filename>.  Он
      автоматически устанавливается как часть порта <filename
      role="package">textproc/docproj</filename>.</para>

    <sect2>
      <title>Расширения FreeBSD</title>

      <para>Проект Документирования FreeBSD расширил DocBook DTD, добавив
	некоторые новые элементы.  Эти элементы служат для уточнения некоторых
	элементов разметки.</para>

      <para>Когда в списке ниже встречается элемент, специфичный для FreeBSD,
	это будет явно указано.</para>

      <para>В оставшемся тексте этого документа термин <quote>DocBook</quote>
	используется в смысле DocBook DTD, расширенного во FreeBSD.</para>

      <note>
	<para>В этих расширениях нет ничего, специфичного для FreeBSD, просто
	  было чувство, что эти расширения оказались полезными для этого
	  конкретного проекта.  Если кто-то из других команд *nix (NetBSD,
	  OpenBSD, Linux, &hellip;) заинтересуется в совместной работе над
	  стандартным набором расширений DocBook, пожалуйста, свяжитесь с
	  &a.doceng;.</para>
      </note>

      <para>Расширений FreeBSD (на данный момент) нет в коллекции портов.  Они
	хранятся в дереве CVS FreeBSD как <ulink
	url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">
	doc/share/sgml/freebsd.dtd</ulink>.</para>
    </sect2>

    <sect2>
      <title>Формальный Публичный Идентификатор (Formal Public
	Identifier - FPI)</title>

      <para>В соответствии с рекомендациями DocBook по написанию FPI для
	собственный настроек DocBook, FPI расширенного DocBook DTD для FreeBSD
	такова;</para>

      <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
    </sect2>

    <sect2>
      <title>Структура документа</title>

      <para>DocBook позволяет вам структурировать документ несколькими
	способами.  В Проекте Документирования FreeBSD мы используем два
	основных типа документа DocBook: книга (book) и статья
	(article).</para>

      <para>Книга организуется в виде глав (<sgmltag>chapter</sgmltag>).  Это
	обязательное условие.  Между книгой и главой могут быть части
	(<sgmltag>part</sgmltag>) для того, чтобы дать дополнительный уровень
	организации.  Руководство организовано именно так.</para>

      <para>Глава может содержать (или может не содержать) один или большее
	количество разделов.  Это выделяется элементом
	<sgmltag>sect1</sgmltag>.  Если раздел содержит другой подраздел, то
	используются элемент <sgmltag>sect2</sgmltag> и так далее, до
	<sgmltag>sect5</sgmltag>.</para>

      <para>В главах и разделах содержится оставшийся текст.</para>

      <para>Статья устроена проще, чем книга, в ней не используются главы.
	Вместо них содержимое статьи организуется в один или большее количество
	разделов, с использованием те же самые элементы
	<sgmltag>sect1</sgmltag> (<sgmltag>sect2</sgmltag> и так далее), что
	используются в книгах.</para>

      <para>Очевидно, что вы должны следовать характеру документа, который вы
	создаете, для решения того, лучше размечать его как книгу или как
	статью.  Статьи хорошо подходят для информации, которую не нужно
	разбивать дальше на несколько глав, и которая имеет относительно
	небольшой объем, до 20-25 страниц текста.  Книги лучше подходят для
	информации, которая может разбиваться на несколько глав, возможно, с
	примечаниями и тому подобным содержимым.</para>

      <para>Все <ulink url="&url.base;/ru/docs.html">учебники FreeBSD</ulink>
	размечены как статьи, <ulink url="&url.books.faq;/index.html">FAQ по
	FreeBSD</ulink> и <ulink url="&url.books.handbook;/index.html">Руководство по
	FreeBSD</ulink> размечены как книги.</para>

      <sect3>
	<title>Начало книги</title>

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

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

	<example>
	  <title>Заготовка для <sgmltag>book</sgmltag> с
	    <sgmltag>bookinfo</sgmltag></title>

	  <!-- Невозможно поместить это в размеченный раздел из-за
	       замещаемых элементов -->
	  <programlisting>&lt;book>
  &lt;bookinfo>
    &lt;title><replaceable>Здесь ваш заголовок</replaceable>&lt;/title>

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

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

    &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>

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

  &hellip;

&lt;/book></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Начало статьи</title>

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

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

	<example>
	  <title>Заготовка <sgmltag>article</sgmltag> с
	    <sgmltag>articleinfo</sgmltag></title>

	  <!-- Невозможно поместить это в размеченный раздел из-за
	       замещаемых элементов -->
	  <programlisting>&lt;article>
  &lt;articleinfo>
    &lt;title><replaceable>Здесь ваш заголовок</replaceable>&lt;/title>

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

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

    &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>

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

  &hellip;

&lt;/article></programlisting>
	</example>	
      </sect3>

      <sect3>
	<title>Оформление глав</title>

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

	<example>
	  <title>Простая глава</title>

	  <programlisting><![ CDATA [<chapter>
  <title>Заголовок главы</title>

  ...
</chapter>]]></programlisting>
	</example>

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

	<example>
	  <title>Пустые главы</title>

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

  <para></para>
</chapter>]]></programlisting>	
	</example>
      </sect3>

      <sect3>
	<title>Секции ниже глав</title>

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

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

	<example>
	  <title>Разделы в главах</title>

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

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

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

    &hellip;
  </sect1>

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

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

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

	&hellip;
      </sect3>
    </sect2>

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

      &hellip;
    </sect2>
  </sect1>
</chapter>]]></programlisting>
	</example>

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

      <sect3>
	<title>Разбиение при помощи <sgmltag>part</sgmltag></title>

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

	<programlisting><![ CDATA [<part>
  <title>Введение</title>

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

    ...
  </chapter>

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

    ...
  </chapter>

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

    ...
  </chapter>
</part>]]></programlisting>
      </sect3>
    </sect2>

    <sect2>
      <title>Блочные элементы</title>

      <sect3>
	<title>Параграфы</title>

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

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

	<example>
	  <title><sgmltag>para</sgmltag></title>
	
	  <para>Использование:</para>

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

	  <para>Результат обработки:</para>

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

      <sect3>
	<title>Блочное цитирование</title>

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

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

	<example>
	  <title><sgmltag>blockquote</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <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>	
	</example>
      </sect3>

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

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

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

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

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

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

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

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

	<example>
	  <title><sgmltag>warning</sgmltag></title>
	
	  <para>Использование:</para>

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

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

      <sect3>
	<title>Списки и процедуры</title>

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

	<para>Для этого используйте элементы <sgmltag>itemizedlist</sgmltag>,
	  <sgmltag>orderedlist</sgmltag> или <sgmltag>procedure</sgmltag>
	  <footnote>
	    <para>В DocBook есть и другие типы элементов списка, но пока мы их
	      не рассматриваем.</para>
	  </footnote>
	</para>

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

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

	<example>
	  <title><sgmltag>itemizedlist</sgmltag>,
	    <sgmltag>orderedlist</sgmltag> и
	    <sgmltag>procedure</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>
	
	  <para>Получаемый результат:</para>

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

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

	<!-- Нельзя помещать <procedure> внутрь <example>, это уловка -->

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

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

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

      <sect3>
	<title>Показ примеров файлов</title>

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

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

	<example>
	  <title><sgmltag>programlisting</sgmltag></title>
	
	  <para>Использование:</para>

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

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

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

	  <para>Отметьте, что угловые скобки в строке
	    <literal>#include</literal> нужно описывать по их соответствующим
	    сущностям, а не напрямую.</para>

	  <para>Результат выдачи:</para>

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

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

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

      <sect3>
	<title>Отсылки</title>

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

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

	<example>
	  <title><sgmltag>co</sgmltag> и <sgmltag>calloutlist</sgmltag></title>

	  <programlisting><![ CDATA[<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>]]></programlisting>

	  <para>Результат обработки:</para>

	  <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>
	</example>
      </sect3>

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

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

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

	<example>
	  <title><sgmltag>informaltable</sgmltag></title>
	
	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выдаваемый результат:</para>

	  <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>
	</example>

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

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

	<example>
	  <title>Таблицы с <literal>frame="none"</literal></title>

	  <para>Выдаваемый результат:</para>

	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Примеры, которым нужно следовать пользователю</title>

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

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

	<variablelist>
	  <varlistentry>
	    <term><sgmltag>screen</sgmltag></term>
	
	    <listitem>
	      <para>Все, что пользователь видит в этом примере на экране
	        компьютера, поэтому элемент и называется
	        <sgmltag>screen</sgmltag>.</para>

	      <para>Внутри <sgmltag>screen</sgmltag>, пробелы имеют
	        значение.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><sgmltag>prompt</sgmltag>,
	      <literal>&amp;prompt.root;</literal> и
	      <literal>&amp;prompt.user;</literal></term>

	    <listitem>
	      <para>Часть из того, что пользователь увидит на экране, является
	        приглашением компьютера (от ОС, командного процессора или
	        прикладной программы.  Это должно быть размечено при помощи
		<sgmltag>prompt</sgmltag>.</para>

	      <para>Как особый случай, для двух приглашений для обычного
	        пользователя и для администратора даны сущности.  Каждый раз,
	        когда вы хотите указать, что пользователь работает с
	        приглашением оболочки, используйте по необходимости
	        <literal>&amp;prompt.root;</literal> или
		<literal>&amp;prompt.user;</literal>.  Их не нужно заключать
	        внутрь <sgmltag>prompt</sgmltag>.</para>

	      <note>
		<para><literal>&amp;prompt.root;</literal> и
		  <literal>&amp;prompt.user;</literal> являются расширениями
	          FreeBSD для DocBook, и не являются частью исходного
		  DTD.</para>
	      </note>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><sgmltag>userinput</sgmltag></term>

	    <listitem>
	      <para>При выводе текста, который должен набрать пользователь,
	        заключите его в метки <sgmltag>userinput</sgmltag>.  Он, скорее
	        всего, будет выведен другим образом.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<example>
	  <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag> и
	    <sgmltag>userinput</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выводимый результат:</para>

	  <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>
	</example>

	<note>
	  <para>Хотя мы выводим содержимое файла <filename>foo2</filename>, оно
	    <emphasis>не</emphasis> размечается как
	    <sgmltag>programlisting</sgmltag>.
	    <sgmltag>programlisting</sgmltag> предназначен для вывода фрагментов
	    файлов вне связи с действиями пользователя.</para>
	</note>
      </sect3>
    </sect2>

    <sect2>
      <title>Строчные элементы</title>

      <sect3>
	<title>Выделение информации</title>

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

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

	<example>
	  <title><sgmltag>emphasis</sgmltag></title>

	  <para>Использование:</para>

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

	  <para>Выводимый результат:</para>

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

      <sect3>
	<title>Цитирование</title>

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

	<example>
	  <title>Цитирование</title>

	  <para>Использование:</para>

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

	  <para>Выводимый результат:</para>

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

      </sect3>

      <sect3>
	<title>Клавиши, кнопки мыши и комбинации</title>

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

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

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

	<example>
	  <title>Клавиши, кнопки мыши и комбинации</title>
	
	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выводимый результат:</para>
	
	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Прикладные программы, команды, параметры и цитаты</title>

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

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

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

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

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

	<para>Это может оказаться громоздким при написании, поэтому для
	  облегчения этой задачи был создан набор <link
	  linkend="sgml-primer-general-entities">сущностей общего
	  назначения</link>.  Каждая сущность имеет форму
	  <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>

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

	<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>

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

	<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
%man;

&hellip;

]&gt;</programlisting>

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

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

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

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

	<example>
	  <title>Приложения, команды и параметры.</title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выводимый результат:</para>

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

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

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

	<note>
	  <para>Заметьте, насколько легче использовать нотацию
	    <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>.</para>
	</note>
      </sect3>

      <sect3>
	<title>Файлы, каталоги, расширения</title>

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

	<example>
	  <title><sgmltag>filename</sgmltag></title>
	
	  <para>Использование:</para>

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

	  <para>Выводимый результат:</para>

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

      <sect3>
	<title>Названия портов</title>

	<note>
	  <title>Расширение FreeBSD</title>

	  <para>Эти элементы являются частями расширения FreeBSD к DocBook, и
	    их нет в исходном DocBook DTD.</para>
	</note>

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

	<example>
	  <title><sgmltag>filename</sgmltag> с аттрибутом
	     <literal>role</literal></title>

	  <para>Использование:</para>

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

	  <para>Выводимый результат:</para>
	
	  <para>Установите <filename role="package">net/ethereal</filename>
	    для просмотра сетевого
	    трафика.</para>
	</example>
      </sect3>

      <sect3>
	<title>Устройства</title>

	<note>
	  <title>Расширение FreeBSD</title>

	  <para>Эти элементы являются частью расширения FreeBSD к DocBook, и их
	    их нет в исходном DocBook DTD.</para>
	</note>

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

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

	<example>
	  <title><sgmltag>devicename</sgmltag></title>
	
	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выводимый результат:</para>

	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Хосты, домены, адреса IP и так далее</title>

	<note>
	  <title>Расширение FreeBSD</title>

	  <para>Эти элементы являются частями расширения FreeBSD к DocBook, и
	    их нет в исходном DocBook DTD.</para>
	</note>

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

	<variablelist>
	  <varlistentry>
	    <term>Без ролевого атрибута или
	      <literal>role="hostname"</literal></term>

	    <listitem>
	      <para>Без ролевого атрибута (то есть
		<sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag>
	        размечаемая информация представляет собой просто имя хоста,
	        такое, как <literal>freefall</literal> или
	        <literal>wcarchive</literal>.  Вы можете явно задать его при
	        помощи <literal>role="hostname"</literal>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="domainname"</literal></term>
	
	    <listitem>
	      <para>Текст является именем домена, таким, как
		<literal>FreeBSD.org</literal> или
		<literal>ngo.org.uk</literal>.  Компонент с именем хоста здесь
	        отсутствует.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="fqdn"</literal></term>
	
	    <listitem>
	      <para>Текст является Полным Доменным Именем, с доменной и
	        хостовой частями.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="ipaddr"</literal></term>
	
	    <listitem>
	      <para>Текст является адресом IP, чаще всего записанном в виде
	        четверки чисел через точку.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="ip6addr"</literal></term>

	    <listitem>
	      <para>Текст является адресом IPv6.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="netmask"</literal></term>

	    <listitem>
	      <para>Текст является сетевой маской, которая может быть записана
	        как четверка чисел через точку, в виде шестнадцатеричной
	        строки или как <literal>/</literal>, за которым следует
	        число.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="mac"</literal></term>
	
	    <listitem>
	      <para>Текст является MAC-адресом Ethernet, записанном в виде
	        последовательности 2-символьных шестнадцатеричных чисел,
	        разделенных двоеточиями.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<example>
	  <title><sgmltag>hostid</sgmltag> и роли</title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выводимый результат:</para>

	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Имена пользователей</title>

	<note>
	  <title>Расширение FreeBSD</title>

	  <para>Эти элементы являются частями расширения FreeBSD к DocBook, и
	    их нет в исходном DocBook DTD.</para>
	</note>

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

	<example>
	  <title><sgmltag>username</sgmltag></title>
	
	  <para>Использование:</para>

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

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

      <sect3>
	<title>Описание <filename>Makefile</filename>s</title>
	
	<note>
	  <title>Расширение FreeBSD</title>

	  <para>Эти элементы являются частями расширения FreeBSD к DocBook, и
	    их нет в исходном DocBook DTD.</para>
	</note>
	
	<para>Для описания частей файлов <filename>Makefile</filename> имеются
	  два элемента, <sgmltag>maketarget</sgmltag> и
	  <sgmltag>makevar</sgmltag>.</para>

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

	<example>
	  <title><sgmltag>maketarget</sgmltag> и
	    <sgmltag>makevar</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [<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>]]></programlisting>

	  <para>Выводимый результат:</para>

	  <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>
	</example>
      </sect3>

      <sect3>
	<title>Дословный текст</title>

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

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

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

	<example>
	  <title><sgmltag>literal</sgmltag></title>
	
	  <para>Использование:</para>

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

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

      <sect3>
	<title>Выделение пунктов, которые пользователь
	  <emphasis>должен</emphasis> заполнить</title>

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

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

	<example>
	  <title><sgmltag>replaceable</sgmltag></title>

	  <para>Использование:</para>
	
	  <programlisting><![ CDATA [<informalexample>
  <screen>&prompt.user; <userinput>man <replaceable>команда</replaceable></userinput></screen>
</informalexample>]]></programlisting>

	  <para>Выводимый результат:</para>

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

	  <para><sgmltag>replaceable</sgmltag> может быть использован во многих
	    различных элементах, включая <sgmltag>literal</sgmltag>.  Этот
	    пример также показывает, что <sgmltag>replaceable</sgmltag> должен
	    окружать только то содержимое, которое пользователь
	    <emphasis>должен</emphasis> заменить.  Все остальное изменять не
	    нужно.</para>

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

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

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

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

      <sect3>
	<title>Цитирование системных сообщений об ошибках</title>

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

	<example>
	  <title><sgmltag>errorname</sgmltag></title>

	  <para>Использование:</para>

	  <programlisting><![ CDATA [
<screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
</programlisting>

	  <para>Выводимый результат:</para>

	  <informalexample>
	    <screen><errorname>Panic: cannot mount root</errorname></screen>
	  </informalexample>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Изображения</title>

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

	<para>Вам также потребуется установить порт
	  <filename role="package">graphics/ImageMagick</filename>,
	  который используется для
	  преобразований между различными графическими форматами.  Это большой
	  порт, и основной его объем не нужен.  Однако, пока мы работаем над
	  файлами <filename>Makefile</filename> и другой инфраструктурой, проще
	  всего использовать его.  Этот порт <emphasis>не</emphasis> входит в
	  мета-порт <filename role="package">textproc/docproj</filename>,
	  вы должны установить его вручную.</para>

	<para>Лучшим примером того, чему нужно следовать на практике, является
	  документ
	  <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>.  Если
	  вам будут не совсем понятны последующие объяснения, взгляните на
	  файлы в этом каталоге, чтобы посмотреть, как все это работает вместе.
	  Поэкспериментируйте с созданием версий документа с разным
	  форматированием, чтобы посмотреть, как выводятся размеченные
	  изображения.</para>
      </important>

      <sect3>
	<title>Форматы изображений</title>

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

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

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

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

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

	<important>
	  <para>Предполагается, что Проект Документирования перейдет на
	    использование формата SVG (Scalable Vector Graphic - масштабируемая
	    векторная графика) для векторных изображений.  Однако текущее
	    состояние инструментов, которые могут редактировать SVG, делает
	    этот переход непрактичным.</para>
	</important>
      </sect3>

      <sect3>
	<title>Разметка</title>

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

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

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

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

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

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

	<programlisting>&lt;mediaobject>
  &lt;imageobject>
    &lt;imagedata fileref="fig1"> <co id="co-image-ext">
  &lt;/imageobject>

  &lt;textobject>
    &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal">
|       A       |
+---------------+&lt;/literallayout>
  &lt;/textobject>

  &lt;textobject>
    &lt;phrase>Рисунок&lt;/phrase> <co id="co-image-phrase">
  &lt;/textobject>
&lt;/mediaobject></programlisting>

	<calloutlist>
	  <callout arearefs="co-image-ext">
	    <para>Помещение элемента <sgmltag>imagedata</sgmltag> внутрь
	      элемента <sgmltag>imageobject</sgmltag>.  Атрибут
	      <literal>fileref</literal> должен содержать имя файла включаемого
	      изображения, без расширения.  Таблицы стилей автоматически
	      определят, какое расширение должно быть добавлено к имени
	      файла.</para>
	  </callout>

	  <callout arearefs="co-image-literal">
	    <para>Первый <sgmltag>textobject</sgmltag> должен содержать элемент
	      <sgmltag>literallayout</sgmltag>, в котором атрибут
	      <literal>class</literal> задан как <literal>monospaced</literal>.
	      Это ваша возможность продемонстрировать свое мастерство в создании
	      изображений в ASCII.  Это содержимое будет использоваться, если
	      документ будет преобразовываться в формат обычного текста.</para>

	    <para>Отметьте, что первая и последняя строки содержимого элемента
	      <sgmltag>literallayout</sgmltag> располагаются впритык к меткам
	      элемента.  Это избавляет от включения дополнительных
	      пробелов.</para>
	  </callout>

	  <callout arearefs="co-image-phrase">
	    <para>Второй <sgmltag>textobject</sgmltag> должен содержать
	      единственный элемент <sgmltag>phrase</sgmltag>.  Его содержимое
	      станет атрибутом <literal>alt</literal> для изображения при
	      преобразовании документа в формат HTML.</para>
	  </callout>
	</calloutlist>
      </sect3>

      <sect3>
	<title>Строки в <filename>Makefile</filename></title>

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

	<programlisting>&hellip;
IMAGES= fig1.eps fig2.png fig3.png
&hellip;</programlisting>

	<para>или же</para>

	<programlisting>&hellip;
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
&hellip;</programlisting>

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

      <sect3>
	<title>Изображения и главы в подкаталогах</title>

	<para>Вы должны быть аккуратны при разбиении вашей документации на
	  файлы меньшего размера (посмотрите <xref
	  linkend="sgml-primer-include-using-gen-entities">), которые находятся
	  в различных каталогах.</para>

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

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

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

	<programlisting>&lt;mediaobject>
  &lt;imageobject>
    &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir">
  &lt;/imageobject>

  &hellip;

&lt;/mediaobject></programlisting>

	<calloutlist>
	  <callout arearefs="co-image-dir">
	    <para>Имя каталога должно быть указано в атрибуте
	      <literal>fileref</literal></para>
	  </callout>
	</calloutlist>

	<para><filename>Makefile</filename> должен содержать</para>

	<programlisting>&hellip;
IMAGES=  chapter1/fig1.png
&hellip;</programlisting>

	<para>Теперь все должно работать.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Ссылки</title>

      <note>
	<para>Ссылки также являются строчными элементами.</para>
      </note>

      <sect3>
	<title>Отсылки на другие части того же самого документа</title>

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

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

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

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

	<example>
	  <title><literal>id в главах и разделах</literal></title>

	  <programlisting><![ CDATA [<chapter id="chapter1">
  <title>Введение</title>

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

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

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

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

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

	<example>
	  <title><sgmltag>anchor</sgmltag></title>

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

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

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

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

	<example>
	  <title>Использование <sgmltag>xref</sgmltag></title>

	  <para>Положим, что этот фрагмент появился где-то в документе, который
	    включает пример с <literal>id</literal>;</para>

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

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

	  <para>Текст ссылки будет сгенерирован автоматически, и будет
	    выглядеть как (<emphasis>выделенный</emphasis> текст, который будет
	    ссылкой);</para>

	  <blockquote>
	    <para>Дополнительная информация может быть найдена в
	      <emphasis>Глава Один</emphasis>.</para>

	    <para>Более конкретная информация находится в <emphasis>разделе с
	      названием Подраздел 1</emphasis>.</para>
	  </blockquote>
	</example>

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

	<note>
	  <para>Это значит, что вы <emphasis>не можете</emphasis> использовать
	    <sgmltag>xref</sgmltag> для отсылки на атрибут
	    <literal>id</literal> элемента <sgmltag>anchor</sgmltag>.  Элемент
	    <sgmltag>anchor</sgmltag> не имеет содержимого, так что
	    <sgmltag>xref</sgmltag> не сможет сгенерировать текст для
	    ссылки.</para>
	</note>
	
	<para>Если вы хотите управлять текстом ссылки, то используйте
	  <sgmltag>link</sgmltag>.  В этот элемент помещается содержимое,
	  которое будет использоваться для ссылки.</para>

	<example>
	  <title>Использование <sgmltag>link</sgmltag></title>

	  <para>Предположим, что этот фрагмент появляется где-то в документе,
	    который включает в себя пример с <literal>id</literal>.</para>

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

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

	  <para>Это приведет к генерации следующего
	    (<emphasis>выделенного</emphasis> текста, который отмечает текст,
	    являющийся ссылкой);</para>

	  <blockquote>
	    <para>Дополнительная информация может быть найдена в
	      <emphasis>первой главе</emphasis>.</para>

	    <para>Более конкретная информация находится в
	      <emphasis>этом</emphasis> разделе.</para>
	  </blockquote>
	</example>

	<note>
	  <para>Последний пример плох.  Никогда не используйте слова типа
	    <quote>этот</quote> или <quote>здесь</quote> в качестве источника
	    ссылки.  Читателю потребуется изучать окружающий текст, чтобы
	    выяснить, куда собственно привела ссылка.</para>
	</note>

	<note>
	  <para>Вы <emphasis>можете</emphasis> использовать
	    <sgmltag>link</sgmltag> для включения ссылки на
	    <literal>id</literal> в элементе <sgmltag>anchor</sgmltag>, так как
	    содержимое <sgmltag>link</sgmltag> задает текст, используемый для
	    ссылки.</para>
	</note>
      </sect3>

      <sect3>
	<title>Ссылки на документы в WWW</title>

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

	<example>
	  <title><sgmltag>ulink</sgmltag></title>

	  <para>Использование:</para>

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

	  <para>Выводимый результат:</para>

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

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
