Проект Документирования 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.