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