1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
<!--
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>
|
