Initial import, synchronized with English 1.12

svn path=/www/; revision=6166
1999-12-14 04:38:25 +00:00 · 1999-12-14 04:38:25 +00:00 · 529f845f3d · 2020-12-08 03:00:23 +00:00
commit 529f845f3d
parent 2caf4ad962
1 changed files with 195 additions and 0 deletions
--- a/ru/docproj/sgml.sgml
+++ b/ru/docproj/sgml.sgml
@ -0,0 +1,195 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
+<!ENTITY base CDATA "..">
+<!ENTITY date "$FreeBSD: www/en/docproj/sgml.sgml,v 1.11 1999/09/19 10:20:46 wosch Exp $">
+<!ENTITY title "FreeBSD Documentation Project: SGML">
+<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
+]>
+<!-- $FreeBSD: www/en/docproj/sgml.sgml,v 1.11 1999/09/19 10:20:46 wosch Exp $ -->
+
+<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".
+      Этот язык был разработан специально для написания технической
+      документации, и поэтому в нем имеется множество тэгов (это нечто,
+      находящееся внутри &lt;...&gt;) для описания всего, что связано с
+      технической документацией.</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, и так далее) отвечает за то, чтобы все строки с
+	  &lt;filename&gt; выглядели одинаково.</p>
+      </li>
+
+      <li><p>Вы перестаете думать о том, как будет выглядеть ваш документ,
+	  и сосредотачиваетесь на содержимом.</p>
+
+      <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;/tutorials/docproj-primer/"><b>Documentation Project
+      Primer</b></a>.  Этот документ является подробным описанием всего,
+      что вам нужно знать для работы с документации FreeBSD.</p>
+
+    <p>Это большой документ, разделенный на много меньших файлов.  Вы можете
+      также просматривать его в виде <a
+      href="&base;/tutorials/docproj-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-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html"><b>http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.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>
+
+      <dt><a
+	href="http://fallout.campusview.indiana.edu/~jfieber/docbook/"><b>http://fallout.campusview.indiana.edu/~jfieber/docbook/</b></a></dt>
+
+      <dd><p>На странице Джона Фибера (John Fieber) находятся ссылки на
+	ресурсы, посвященные DocBook и примеры документов.  Там также
+	имеется начало руководства по разметке для FreeBSD.</dd>
+
+      <dt><a
+	href="http://www.nothing-going-on.demon.co.uk/FreeBSD/"><b>http://www.nothing-going-on.demon.co.uk/FreeBSD/</b></a></dt>
+
+      <dd><p>Страница Ника Клэйтона (Nik Clayton) содержит ссылки на
+	документацию, написанную в DocBook, а затем преоразованну в HTML.
+	Доступны оригинальные файлы в формате DocBook, и дается достаточно
+	большой пример того, как могут быть использованы различные элементы
+	DocBook.</p></dd>
+
+      <dt><a
+	href="http://www.FreeBSD.org/~wosch/papers/webbuild.html"><b>
+	http://www.FreeBSD.org/~wosch/papers/webbuild.html</b></a></dt>
+
+      <dd> &webbuild; </dd>
+    </dl>
+
+      <p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
+&footer;
+  </body>
+</html>