Глава 4. Разметка SGML

Содержание
4.1. HTML
4.2. DocBook

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

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

Это не исчерпывающий список элементов, так как это стало бы простым повторением документации по каждому языку. Предназначение этого раздела заключается в перечислении тех элементов, которые в первую очередь будут полезными для вас. Если у вас есть вопрос по поводу наилучшей разметки конкретного текста, пожалуйста, пошлите его по адресу Список рассылки Проекта Документации FreeBSD

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

4.1. HTML

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

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

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

DTD для HTML доступны из коллекции портов через порт textproc/html. Они автоматически устанавливаются как часть порта textproc/docproj.

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

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

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

PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

4.1.2. Элементы разделов

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

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

Пример 4-1. Обычная структура документа HTML

<html>
  <head>
      <title>Заголовок документа</title>
  </head>

  <body>

    ...

  </body>
</html>

4.1.3. Блочные элементы

4.1.3.1. Заголовки

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

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

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

Пример 4-2. <h1>, <h2> и так далее.

Использование:

<h1>First section</h1>

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

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

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

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

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

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

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

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

Пример 4-3. Неправильный порядок следования элементов <hn>

Использование:

<h1>Первый раздел</h1>

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

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

<!-- Это плохо, пропущен <h2> -->

4.1.3.2. Параграфы

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

Пример 4-4. <p>

Использование:

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

4.1.3.3. Цитирование блока

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

Пример 4-5. <blockquote>

Использование:

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

4.1.3.4. Списки

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

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

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

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

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

Пример 4-6. <ul> и <ol>

Использование:

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

Пример 4-7. Списки определений с <dl>

Использование:

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

4.1.3.5. Предварительно отформатированный текст

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

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

Пример 4-8. <pre>

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

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

4.1.3.6. Таблицы

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

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

Пример 4-9. Простое использование <table>

Использование:

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

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

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

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

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

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

Пример 4-10. Использование rowspan

Использование:

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

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

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

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

Пример 4-11. Использование colspan

Использование:

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

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

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

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

Пример 4-12. Использование rowspan и colspan одновременно

Использование:

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

4.1.4. Строчные элементы

4.1.4.1. Выделяющая информация

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

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

Пример 4-13. <em> и <strong>

Использование:

<p><em>Этот текст</em> выделен, а
  <strong>этот текст</strong> выделен сильно.</p>

4.1.4.2. Жирный и наклонный

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

Пример 4-14. <b> и <i>

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

4.1.4.3. Указание текста одинаковой ширины

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

Пример 4-15. <tt>

Использование:

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

4.1.4.4. Размер текста

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

  1. Используйте <big> и <small> вокруг содержимого, размер которого вы хотите изменить. Эти метки могут быть вложенными, так, возможно выводить <big><big>этот текст гораздо крупнее</big></big>.

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

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

Пример 4-16. <big>, <small> и <font>

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

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

4.1.5. Ссылки

Замечание: Ссылки также являются внутристрочными элементами.

4.1.5.1. Ссылки на другие документы на WWW

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

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

Пример 4-17. Использование <a href="...">

Использование:

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

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

4.1.5.2. Ссылки на другие части документов

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

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

Пример 4-18. Использование <a name="...">

Использование:

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

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

Пример 4-19. Ссылка на именованную часть другого документа

Предположим, что пример с para1 расположен в документе с именем foo.html.

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

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

Пример 4-20. Ссылка на именованную часть того же самого документа

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

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

Этот, и другие документы, могут быть скачаны с ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

По вопросам, связанным с FreeBSD, прочитайте документацию прежде чем писать в <questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите <doc@FreeBSD.org>.
По вопросам, связанным с русским переводом документации, пишите в рассылку <frdp@FreeBSD.org.ua>.
Информация по подписке на эту рассылку находится на сайте проекта перевода.