843f00d7b1
1.22 -> 1.42 docproj/current.sgml 1.6 -> 1.12 docproj/doc-set.sgml 1.14 -> 1.16 docproj/docproj.sgml 1.22 -> 1.23 docproj/handbook3.sgml 1.19 -> 1.22 docproj/sgml.sgml 1.6 -> 1.13 docproj/submitting.sgml 1.36 -> 1.55 docproj/translations.sgml 1.6 -> 1.11 docproj/who.sgml Approved by: phantom (mentor)
182 lines
7.4 KiB
Text
182 lines
7.4 KiB
Text
<!--
|
||
The FreeBSD Russian Documentation Project
|
||
|
||
$FreeBSDru: frdp/www/ru/docproj/sgml.sgml,v 1.8 2003/10/09 11:25:02 den Exp $
|
||
|
||
Original revision: 1.22
|
||
-->
|
||
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
|
||
<!ENTITY base CDATA "..">
|
||
<!ENTITY date "$FreeBSD$">
|
||
<!ENTITY title "Проект Документирования FreeBSD: SGML">
|
||
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
||
]>
|
||
|
||
<html>
|
||
&header;
|
||
|
||
<p>The Documentation Project пытается использовать SGML в качестве
|
||
стандартного средства для написания документации.</p>
|
||
|
||
<p>Сокращение SGML означает <b>S</b>tandard <b>G</b>eneralised
|
||
<b>M</b>arkup <b>L</b>anguage (Стандартный Формализованный Язык
|
||
Разметки).</p>
|
||
|
||
<p>По сути (и да простят нас SGML-пуристы, присутствующие среди
|
||
аудитории, к которой мы обращаемся) SGML является языком для написания
|
||
других языков.</p>
|
||
|
||
<p>Скорее всего, вы уже работали с SGML, не подозревая об этом. HTML,
|
||
язык, на котором пишутся страницы веба, имеет формальное описание. Это
|
||
описание написано на SGML. Когда вы пишете в HTML, вы <b>не</b>
|
||
пишете на SGML (per se), но используете язык, заданный при помощи
|
||
SGML.</p>
|
||
|
||
<p>Существует много, очень много языков разметки, которые заданы с
|
||
помощью SGML. HTML - один из них. Другой называется "LinuxDoc".
|
||
Как вы уже, наверное, догадались, он был создан группой,
|
||
документирующей Linux, для написания документации, и используется во
|
||
FreeBSD Documentation Project.</p>
|
||
|
||
<p>Другим языком разметки, заданным с помощью SGML, является "DocBook".
|
||
Этот язык был разработан специально для написания технической
|
||
документации, и поэтому в нем имеется множество тегов (это нечто,
|
||
находящееся внутри <...>) для описания всего, что связано с
|
||
технической документацией.</p>
|
||
|
||
<p>Например, вот так может выглядеть короткий параграф в HTML
|
||
(не обращайте внимания на содержимое, смотрите на теги):</p>
|
||
|
||
<pre><![ CDATA [
|
||
<p>Пароли хранятся в <tt>/etc/passwd</tt>. Чтобы отредактировать этот
|
||
файл, вы должны использовать <b><tt>vipw</tt></b>. Однако, если вам
|
||
нужно только добавить в систему нового пользователя, вы можете
|
||
воспользоваться утилитой <b><tt>adduser</tt></b>.</p>
|
||
]]></pre>
|
||
|
||
<p>Тот же параграф, оформленный в стандарте DocBook, выглядит как</p>
|
||
|
||
<pre><![ CDATA [
|
||
<para>Пароли хранятся в <filename>/etc/passwd</filename>. Чтобы
|
||
отредактировать этот файл, вы должны использовать
|
||
<command>vipw</command>. Однако, если вам нужно только добавить в
|
||
систему нового пользователя, вы можете воспользоваться утилитой
|
||
<command>adduser</command>.</para>
|
||
]]></pre>
|
||
|
||
<p>Как вы можете видеть, DocBook более 'выразителен', чем HTML. В
|
||
примере с HTML задается вывод имени файла шрифтом 'пишущей машинки'.
|
||
В примере с DocBook вывод имени файла задается именно как 'имя файла',
|
||
конкретное представление имени файла не оговаривается.</p>
|
||
|
||
<p>Имеется несколько плюсов использования этой более выразительной формы
|
||
разметки:</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p>В ней нет разночтений или противоречий.</p> <p>Вам не нужно
|
||
терять время, обдумывая "Хм, мне нужно вывести название файла,
|
||
должен ли я использовать 'tt', 'b', или, может, 'em'?"</p>
|
||
|
||
<p>Вместо этого вы просто используете нужный тег в нужном
|
||
месте.</p>
|
||
|
||
<p>Процедура преобразования из DocBook в другие форматы (HTML,
|
||
Postscript®, и так далее) отвечает за то, чтобы все строки с
|
||
<filename> выглядели одинаково.</p>
|
||
</li>
|
||
|
||
<li>
|
||
<p>Вы перестаёте думать о том, как будет выглядеть ваш документ,
|
||
и сосредотачиваетесь на его содержимом.</p></li>
|
||
|
||
<li><p>Так как документация не привязана ни к какому конкретному
|
||
выходному формату, та же самая документация может быть представлена
|
||
во многих различных форматах - просто текст, HTML, PostScript,
|
||
RTF, PDF и так далее.</p></li>
|
||
|
||
<li><p>Документация становится более 'умной', поэтому с ней могут
|
||
быть выполнены более интеллектуальные операции. Например,
|
||
становится возможным автоматически генерировать индекс, в котором
|
||
указаны все команды, упомянутые в документе.</p></li>
|
||
</ul>
|
||
|
||
<p>Если вы знакомы с Microsoft® Word, это похоже на таблицы стилей, только
|
||
гораздо более мощные.</p>
|
||
|
||
<p>Конечно же, эти возможности достигаются определенной ценой;</p>
|
||
|
||
<ul>
|
||
<li><p>Так как тегов, которые вы можете использовать, гораздо больше,
|
||
требуется больше времени на их изучение и понимание того, как
|
||
использовать их эффективно.</p>
|
||
|
||
<p>Я обнаружил, что самым лучших методом обучения является чтение
|
||
исходных текстов множества образцовых документов и сравнение того,
|
||
как разные авторы оформляют подобную информацию.</p></li>
|
||
|
||
<li><p>Процесс преобразования не так уж прост.</p></li>
|
||
</ul>
|
||
|
||
<p>На данный момент Проект все еще использует LinuxDoc для Руководства
|
||
и FAQ. Это положение меняется, в частности, идет процесс
|
||
преобразования документации в формат DocBook.</p>
|
||
|
||
<h2>Что, если вы не знаете LinuxDoc/DocBook? Можете ли вы предоставлять
|
||
нам документацию?</h2>
|
||
|
||
<p>Да, можете. Однозначно. Любая документация лучше, чем ее отсутствие.
|
||
Если у вас есть документация, которую вы хотите нам предоставить, и она
|
||
размечена не в формате LinuxDoc или DocBook, ничего страшного.</p>
|
||
|
||
<p><a href="submitting.html">Пошлите</a> нам документацию обычным
|
||
образом. Кто-нибудь из Проекта рассмотрит документацию, которую вы
|
||
послали, разметит ее за вас и включит в систему. С некоторой
|
||
вероятностью обратно вам будет выслан размеченный текст. Это весьма
|
||
полезно, так как вы сможете сравнить документацию "до и после",
|
||
обычный текст и размеченный, и, может быть, узнаете что-то новое о
|
||
процессе разметки.</p>
|
||
|
||
<p>Как правило, это замедляет процесс включения документации в систему,
|
||
так как предоставленный вами текст должен быть предварительно размечен,
|
||
что может занять вечер или два. Но она будет включена.</p>
|
||
|
||
<h2>Хотите знать больше о SGML и DocBook?</h2>
|
||
|
||
<p>Сначала вы должны прочесть <a
|
||
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/index.html"><b>Documentation Project
|
||
Primer</b></a>. Этот документ является подробным описанием всего,
|
||
что вам нужно знать для работы с документации FreeBSD.</p>
|
||
|
||
<p>Это большой документ, разделенный на много меньших файлов. Вы можете
|
||
также просматривать его в виде <a
|
||
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>одного
|
||
большого файла</b></a>.</p>
|
||
|
||
<dl>
|
||
<dt><a
|
||
href="http://www.oasis-open.org/cover/sgml-xml.html"><b>http://www.oasis-open.org/cover/sgml-xml.html</b></a></dt>
|
||
|
||
<dd><p>Страница SGML/XML. Содержит бесчисленное множество ссылок на
|
||
информацию о SGML.</p></dd>
|
||
|
||
<dt><a
|
||
href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"><b>http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</b></a></dt>
|
||
|
||
<dd><p>"Gentle Introduction to SGML". Рекомендуемое чтение для всех,
|
||
кто хочет изучить SGML более подробно с уровня начинающего.</p></dd>
|
||
|
||
<dt><a
|
||
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
|
||
|
||
<dd><p>DocBook DTD поддерживается OASIS. Эти страницы предназначены
|
||
для пользователей, которые чувствуют себя уверенно с SGML и хотят
|
||
изучить DocBook.</p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
|
||
&footer;
|
||
</body>
|
||
</html>
|