FreeBSD The Power to Serve

Проект Документирования FreeBSD: SGML

The Documentation Project использует SGML в качестве стандартного средства для написания документации.

Сокращение SGML означает Standard Generalized Markup Language (Стандартный Формализованный Язык Разметки).

По сути (и да простят нас SGML-пуристы, присутствующие среди аудитории, к которой мы обращаемся) SGML является языком для написания других языков.

Скорее всего, вы уже работали с SGML, не подозревая об этом. HTML, язык, на котором пишутся страницы web, имеет формальное описание. Это описание написано на SGML. Когда вы пишете в HTML, вы не пишете на SGML (per se), но используете язык, заданный при помощи SGML.

Существует много, очень много языков разметки, которые заданы с помощью SGML. HTML - один из них. Другой называется "DocBook". Этот язык был разработан специально для написания технической документации, и поэтому в нем имеется множество тегов (маркеры в виде <содержимое тегов>) для описания технической документации с последующим форматированием. Проект документирования FreeBSD адаптировал его и определил несколько новых элементов, чтобы сделать его более подходящим.

Например, вот так может выглядеть короткий параграф в HTML (не обращайте внимания на содержимое, смотрите на теги):

    <p>Пароли хранятся в <tt>/etc/passwd</tt>.  Чтобы отредактировать этот
      файл, вы должны использовать <b><tt>vipw</tt></b>.  Однако, если вам
      нужно только добавить в систему нового пользователя, вы можете
      воспользоваться утилитой <b><tt>adduser</tt></b>.</p>

Тот же параграф, оформленный в стандарте DocBook, выглядит как

    <para>Пароли хранятся в <filename>/etc/passwd</filename>.  Чтобы
      отредактировать этот файл, вы должны использовать
      <command>vipw</command>.  Однако, если вам нужно только добавить в
      систему нового пользователя, вы можете воспользоваться утилитой
      <command>adduser</command>.</para>

Как вы можете видеть, DocBook более 'выразителен', чем HTML. В примере с HTML задается вывод имени файла шрифтом 'пишущей машинки'. В примере с DocBook вывод имени файла задается именно как 'имя файла', конкретное представление имени файла не оговаривается.

Имеется несколько плюсов использования этой более выразительной формы разметки:

  • В ней нет разночтений или противоречий.

    Вам не нужно терять время, обдумывая "Хм, мне нужно вывести название файла, должен ли я использовать 'tt', 'b', или, может, 'em'?"

    Вместо этого вы просто используете нужный тег в нужном месте.

    Процедура преобразования из DocBook в другие форматы (HTML, Postscript®, и так далее) отвечает за то, чтобы все элементы <filename> выглядели одинаково.

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

  • Так как документация не привязана ни к какому конкретному выходному формату, та же самая документация может быть представлена во многих различных форматах-просто текст, HTML, PostScript, RTF, PDF и так далее.

  • Документация становится более 'умной', поэтому с ней могут быть выполнены более интеллектуальные операции. Например, становится возможным автоматически генерировать индекс, в котором указаны все команды, упомянутые в документе.

Они похожи на таблицы стилей Microsoft® Word, только гораздо более мощные.

Конечно же, эти возможности достигаются определенной ценой;

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

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

  • Процесс преобразования не так уж прост.

Что, если вы не знаете DocBook? Можете ли вы предоставлять нам документацию?

Да, можете. Однозначно. Любая документация лучше, чем ее отсутствие. Если у вас есть документация, которую вы хотите нам предоставить, и она размечена не в формате DocBook, ничего страшного.

Пошлите нам документацию обычным образом. Кто-нибудь из Проекта рассмотрит документацию, которую вы послали, разметит ее за вас и включит в систему. С некоторой вероятностью обратно вам будет выслан размеченный текст. Это весьма полезно, так как вы сможете сравнить документацию "до и после", т.е. обычный текст и размеченный, и, может быть, узнаете что-то новое о процессе разметки.

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

Хотите знать больше о SGML и DocBook?

Для начала прочтите Documentation Project Primer. Этот документ является подробным описанием всего, что вам нужно знать для работы с документации FreeBSD. Это большой документ, разделенный на много меньших файлов. Вы можете также просматривать его в виде одной большой страницы.

http://www.oasis-open.org/cover/sgml-xml.html

Страница SGML/XML. Содержит бесчисленное множество ссылок на информацию о SGML.

http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html

"Gentle Introduction to SGML". Рекомендуемое чтение для всех, кто хочет изучить SGML более подробно с уровня начинающего.

http://www.oasis-open.org/docbook/

DocBook DTD поддерживается OASIS. Эти страницы предназначены для пользователей, которые чувствуют себя уверенно с SGML и хотят изучить DocBook.


Last modified on: 26 января 2021 г. by Sergio Carlavilla Delgado