diff options
Diffstat (limited to 'ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.xml')
| -rw-r--r-- | ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.xml | 2734 |
1 files changed, 2734 insertions, 0 deletions
diff --git a/ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.xml b/ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.xml new file mode 100644 index 0000000000..2a0d3307cc --- /dev/null +++ b/ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.xml @@ -0,0 +1,2734 @@ +<?xml version="1.0" encoding="koi8-r" standalone="no"?> +<!-- + The FreeBSD Russian Documentation Project + + $FreeBSD$ + $FreeBSDru: frdp/doc/ru_RU.KOI8-R/books/fdp-primer/sgml-markup/chapter.xml,v 1.8 2005/05/07 07:59:46 maxim Exp $ + + Original revision: r23877 +--> + +<!-- 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. Более полная информация может быть найдена + по адресу <URL:<ulink url="http://www.w3.org/"></ulink>>.</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><html> + <head> + <title><replaceable>Заголовок документа</replaceable></title> + </head> + + <body> + + … + + </body> +</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. Заметьте, что элемент <p> + в случае единственного параграфа не нужен.</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><big><big>этот текст гораздо + крупнее</big></big></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><a href="..."></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><a name="..."></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 + & 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, …) заинтересуется в совместной работе над + стандартным набором расширений 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><book> + <bookinfo> + <title><replaceable>Здесь ваш заголовок</replaceable></title> + + <author> + <firstname><replaceable>Ваше имя</replaceable></firstname> + <surname><replaceable>Ваша фамилия</replaceable></surname> + <affiliation> + <address><email><replaceable>Ваш адрес электронной почты</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>Ваш e-mail</replaceable>"><replaceable>Ваше имя</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Сюда включите обзор содержимого книги.</replaceable></para> + </abstract> + </bookinfo> + + … + +</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><article> + <articleinfo> + <title><replaceable>Здесь ваш заголовок</replaceable></title> + + <author> + <firstname><replaceable>Ваше имя</replaceable></firstname> + <surname><replaceable>Ваша фамилия</replaceable></surname> + <affiliation> + <address><email><replaceable>Ваш e-mail</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>Ваш e-mail</replaceable>"><replaceable>Ваше имя</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Сюда включите обзор содержимого статьи.</replaceable></para> + </abstract> + </articleinfo> + + … + +</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> + + … + </sect1> + + <sect1> + <title>Второй раздел (1.2)</title> + + <sect2> + <title>Первый подраздел (1.2.1)</title> + + <sect3> + <title>Второй подподраздел (1.2.1.1)</title> + + … + </sect3> + </sect2> + + <sect2> + <title>Второй подраздел (1.2.2)</title> + + … + </sect2> + </sect1> +</chapter>]]></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 <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Отметьте, что угловые скобки в строке + <literal>#include</literal> нужно описывать по их соответствующим + сущностям, а не напрямую.</para> + + <para>Результат выдачи:</para> + + <para>Когда вы закончите, ваша программа должна + иметь примерно такой вид;</para> + + <programlisting>#include <stdio.h> + +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 <stdio.h> <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 <stdio.h> <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><informaltable + frame="none"></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>&prompt.root;</literal> и + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Часть из того, что пользователь увидит на экране, является + приглашением компьютера (от ОС, командного процессора или + прикладной программы. Это должно быть размечено при помощи + <sgmltag>prompt</sgmltag>.</para> + + <para>Как особый случай, для двух приглашений для обычного + пользователя и для администратора даны сущности. Каждый раз, + когда вы хотите указать, что пользователь работает с + приглашением оболочки, используйте по необходимости + <literal>&prompt.root;</literal> или + <literal>&prompt.user;</literal>. Их не нужно заключать + внутрь <sgmltag>prompt</sgmltag>.</para> + + <note> + <para><literal>&prompt.root;</literal> и + <literal>&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>&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><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + <para>Используйте <sgmltag>command</sgmltag>, когда вы хотите включить + название команды <quote>в строку</quote>, но она должна выглядеть + так, как будто её должен набрать пользователь.</para> + + <para>Для разметки параметров, которые передаются описываемой команде, + используйте <sgmltag>option</sgmltag>.</para> + + <para>Когда Вы ссылаетесь к одной команде несколько раз в течение + короткого периода времени, то предпочтительно использовать нотацию + вида + <literal>&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>&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.xml</filename>. Вы также должны посмотреть на + <filename>Makefile</filename> и некоторое количество файлов с расширением + <filename>.ent</filename>.</para>]]></programlisting> + + <para>Выводимый результат:</para> + + <para>Исходный код SGML для Руководства на английском языке можно + найти в каталоге <filename>/usr/doc/en/handbook/</filename>. В + этом каталоге первый файл называется + <filename>handbook.xml</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><mediaobject> + <imageobject> + <imagedata fileref="fig1"> <co id="co-image-ext"> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ <co id="co-image-literal"> +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>Рисунок</phrase> <co id="co-image-phrase"> + </textobject> +</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>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>или же</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</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.xml</filename>, + <filename>chapter2/chapter.xml</filename> и + <filename>chapter3/chapter.xml</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.xml</filename> должен содержать</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"> + </imageobject> + + … + +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para>Имя каталога должно быть указано в атрибуте + <literal>fileref</literal></para> + </callout> + </calloutlist> + + <para><filename>Makefile</filename> должен содержать</para> + + <programlisting>… +IMAGES= chapter1/fig1.png +…</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> |