The Documentation Project пытается использовать SGML в качестве стандартного средства для написания документации.
Сокращение SGML означает Standard Generalised Markup Language (Стандартный Формализованный Язык Разметки).
По сути (и да простят нас SGML-пуристы, присутствующие среди аудитории, к которой мы обращаемся) SGML является языком для написания других языков.
Скорее всего, вы уже работали с SGML, не подозревая об этом. HTML, язык, на котором пишутся страницы веба, имеет формальное описание. Это описание написано на SGML. Когда вы пишете в HTML, вы не пишете на SGML (per se), но используете язык, заданный при помощи SGML.
Существует много, очень много языков разметки, которые заданы с помощью SGML. HTML - один из них. Другой называется "LinuxDoc". Как вы уже, наверное, догадались, он был создан группой, документирующей Linux, для написания документации, и используется во FreeBSD Documentation Project.
Другим языком разметки, заданным с помощью SGML, является "DocBook". Этот язык был разработан специально для написания технической документации, и поэтому в нем имеется множество тегов (это нечто, находящееся внутри <...>) для описания всего, что связано с технической документацией.
Например, вот так может выглядеть короткий параграф в HTML (не обращайте внимания на содержимое, смотрите на теги):
Пароли хранятся в /etc/passwd. Чтобы отредактировать этот
файл, вы должны использовать vipw. Однако, если вам
нужно только добавить в систему нового пользователя, вы можете
воспользоваться утилитой adduser.
]]>
Тот же параграф, оформленный в стандарте DocBook, выглядит как
Пароли хранятся в/etc/passwd . Чтобы отредактировать этот файл, вы должны использоватьvipw . Однако, если вам нужно только добавить в систему нового пользователя, вы можете воспользоваться утилитойadduser . ]]>
Как вы можете видеть, DocBook более 'выразителен', чем HTML. В примере с HTML задается вывод имени файла шрифтом 'пишущей машинки'. В примере с DocBook вывод имени файла задается именно как 'имя файла', конкретное представление имени файла не оговаривается.
Имеется несколько плюсов использования этой более выразительной формы разметки:
В ней нет разночтений или противоречий.
Вам не нужно терять время, обдумывая "Хм, мне нужно вывести название файла, должен ли я использовать 'tt', 'b', или, может, 'em'?"
Вместо этого вы просто используете нужный тег в нужном месте.
Процедура преобразования из DocBook в другие форматы (HTML, Postscript®, и так далее) отвечает за то, чтобы все строки с <filename> выглядели одинаково.
Вы перестаёте думать о том, как будет выглядеть ваш документ, и сосредотачиваетесь на его содержимом.
Так как документация не привязана ни к какому конкретному выходному формату, та же самая документация может быть представлена во многих различных форматах - просто текст, HTML, PostScript, RTF, PDF и так далее.
Документация становится более 'умной', поэтому с ней могут быть выполнены более интеллектуальные операции. Например, становится возможным автоматически генерировать индекс, в котором указаны все команды, упомянутые в документе.
Если вы знакомы с Microsoft® Word, это похоже на таблицы стилей, только гораздо более мощные.
Конечно же, эти возможности достигаются определенной ценой;
Так как тегов, которые вы можете использовать, гораздо больше, требуется больше времени на их изучение и понимание того, как использовать их эффективно.
Я обнаружил, что самым лучших методом обучения является чтение исходных текстов множества образцовых документов и сравнение того, как разные авторы оформляют подобную информацию.
Процесс преобразования не так уж прост.
На данный момент Проект все еще использует LinuxDoc для Руководства и FAQ. Это положение меняется, в частности, идет процесс преобразования документации в формат DocBook.
Да, можете. Однозначно. Любая документация лучше, чем ее отсутствие. Если у вас есть документация, которую вы хотите нам предоставить, и она размечена не в формате LinuxDoc или DocBook, ничего страшного.
Пошлите нам документацию обычным образом. Кто-нибудь из Проекта рассмотрит документацию, которую вы послали, разметит ее за вас и включит в систему. С некоторой вероятностью обратно вам будет выслан размеченный текст. Это весьма полезно, так как вы сможете сравнить документацию "до и после", обычный текст и размеченный, и, может быть, узнаете что-то новое о процессе разметки.
Как правило, это замедляет процесс включения документации в систему, так как предоставленный вами текст должен быть предварительно размечен, что может занять вечер или два. Но она будет включена.
Сначала вы должны прочесть Documentation Project Primer. Этот документ является подробным описанием всего, что вам нужно знать для работы с документации FreeBSD.
Это большой документ, разделенный на много меньших файлов. Вы можете также просматривать его в виде одного большого файла.
Страница SGML/XML. Содержит бесчисленное множество ссылок на информацию о SGML.
"Gentle Introduction to SGML". Рекомендуемое чтение для всех, кто хочет изучить SGML более подробно с уровня начинающего.
DocBook DTD поддерживается OASIS. Эти страницы предназначены для пользователей, которые чувствуют себя уверенно с SGML и хотят изучить DocBook.