5305bb945d
- Move includes.nav*.sgml to share/sgml/navibar.ent and
<lang>/share/sgml/navibar.l10n.ent.
- Move includes.sgml and includes.xsl to
share/sgml/common.ent, share/sgml/header.ent, <lang>/share/sgml/l10n.ent,
and <lang>/share/sgml/header.l10n.ent.
- Move most of XSLT libraries to share/sgml/*.xsl and
<lang>/share/sgml/*.xsl.
- Move news.xml and other *.xml files for the similar purpose
to share/sgml/*.xml and <lang>/share/sgml/*.xml.
- Switch to use a custom DTD for HTML document. Now we use
"-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension", which is
HTML 4.01 + some entities previously pulled via
"<!ENTITY % includes SYSTEM "includes.sgml"> %includes;" line.
The location of entity file will be resolved by using catalog file.
- Add DOCTYPE declearation to XML documents. This makes the followings
possible:
* Use of &foo; entities for SGML in an XML file instead of defining
{$foo} as the same content.
* &symbolic; entities for Latin characters.
- Duplicated information between SGML and XML, or English and
translated doc, has been removed as much as possible.
173 lines
7.1 KiB
Text
173 lines
7.1 KiB
Text
<!--
|
||
The FreeBSD Russian Documentation Project
|
||
|
||
$FreeBSDru: frdp/www/ru/docproj/sgml.sgml,v 1.10 2006/06/10 05:11:42 gad Exp $
|
||
|
||
Original revision: 1.26
|
||
-->
|
||
|
||
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
|
||
<!ENTITY base CDATA "..">
|
||
<!ENTITY date "$FreeBSD: www/ru/docproj/sgml.sgml,v 1.7 2006/06/10 10:30:17 bvs Exp $">
|
||
<!ENTITY title "Проект Документирования FreeBSD: SGML">
|
||
<!ENTITY % navinclude.docs "INCLUDE">
|
||
]>
|
||
|
||
<html>
|
||
&header;
|
||
|
||
<p>The Documentation Project использует SGML в качестве
|
||
стандартного средства для написания документации.</p>
|
||
|
||
<p>Сокращение SGML означает <b>S</b>tandard <b>G</b>eneralized
|
||
<b>M</b>arkup <b>L</b>anguage (Стандартный Формализованный Язык
|
||
Разметки).</p>
|
||
|
||
<p>По сути (и да простят нас SGML-пуристы, присутствующие среди
|
||
аудитории, к которой мы обращаемся) SGML является языком для написания
|
||
других языков.</p>
|
||
|
||
<p>Скорее всего, вы уже работали с SGML, не подозревая об этом. HTML,
|
||
язык, на котором пишутся страницы web, имеет формальное описание. Это
|
||
описание написано на SGML. Когда вы пишете в HTML, вы <b>не</b>
|
||
пишете на SGML (per se), но используете язык, заданный при помощи
|
||
SGML.</p>
|
||
|
||
<p>Существует много, очень много языков разметки, которые заданы с
|
||
помощью SGML. HTML - один из них. Другой называется "DocBook".
|
||
Этот язык был разработан специально для написания технической
|
||
документации, и поэтому в нем имеется множество тегов (маркеры
|
||
в виде <tt><содержимое тегов></tt>) для описания
|
||
технической документации с последующим форматированием.
|
||
Проект документирования FreeBSD адаптировал его и определил несколько
|
||
новых элементов, чтобы сделать его более подходящим.</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>Хороший способ обучения SGML и DocBook является чтение
|
||
исходных текстов множества образцовых документов и сравнение того,
|
||
как разные авторы оформляют подобную информацию.</p></li>
|
||
|
||
<li><p>Процесс преобразования не так уж прост.</p></li>
|
||
</ul>
|
||
|
||
<h2>Что, если вы не знаете DocBook? Можете ли вы предоставлять
|
||
нам документацию?</h2>
|
||
|
||
<p>Да, можете. Однозначно. Любая документация лучше, чем ее отсутствие.
|
||
Если у вас есть документация, которую вы хотите нам предоставить, и она
|
||
размечена не в формате 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. Это большой
|
||
документ, разделенный на много меньших файлов. Вы можете также просматривать
|
||
его в виде <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>
|