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
|
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "Proyecto de Documentación de FreeBSD: SGML">
<!ENTITY % navinclude.docs "INCLUDE">
]>
<!-- The FreeBSD Spanish Documentation Project
Original Revision: r1.28 -->
<html>
&header;
<p>El proyecto de Documentación usa SGML como
método estándar de representar la documentación.</p>
<p>El nombre SGML viene de <b>S</b>tandard <b>G</b>eneralised
<b>M</b>arkup <b>L</b>anguage, que podría traducirse
como "lenguaje de etiquetado estándar de
propósito general".</p>
<p>Brevemente (y disculpas para los puristas de SGML que puedan sentirse
ofendidos) SGML es un lenguaje para escribir otros lenguajes.</p>
<p>Probablemente ya haya usado SGML sin saberlo. HTML, el lenguaje en el
que se escriben las páginas web, tiene una descripción
formal. Esta descripción se escribió en SGML. Cuando
escribe en HTML <b>no</b> está escribiendo SGML pero sí
que está usando un lenguaje definido por SGML.</p>
<p>Existen muchos, muchos lenguajes "markup" que están definidos
usando SGML. HTML es uno de ellos. Otro es el llamado "DocBook".
Éste es un lenguaje diseñado específicamente para
escribir documentación técnica y tiene muchas etiquetas
o "tags", (por ejemplo <tt><tag contenido></tt>).
FreeBSD lo adoptó y definidó
nuevos elementos para hacerlo más preciso.</p>
<p>Por ejemplo, así se escribiría un breve párrafo
en HTML (no se preocupe del contenido, solo fíjese en las
etiquetas):</p>
<pre><![ CDATA [
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
this file you should use <b><tt>vipw</tt></b>. However, if you just
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
]]></pre>
<p>El mismo párrafo en DocBook sería:</p>
<pre><![ CDATA [
<para>The system's passwords are stored in
<filename>/etc/passwd</filename>. To edit this file you should use
<command>vipw</command>. However, if you just want to add a new user
you can use <command>adduser</command>.</para>
]]></pre>
<p>Como puede ver DocBook es mucho más expresivo que HTML. En el
ejemplo HTML el nombre del fichero se muestra con un tipo de letra
de máquina de escribir. En el ejemplo de DocBook, el nombre
de fichero lleva la etiqueta "filename" (nombre de fichero); la
representación de un nombre de fichero no está
descrita.</p>
<p>Esta mayor expresividad tiene grandes ventajas:</p>
<ul>
<li>
<p>No es ambiguo o inconsistente.</p> <p>No se pierde tiempo
pensando "¿Hmm, necesito mostrar un nombre de fichero,
¿debería usar "tt", o "b", o "em"?</p>
<p>En lugar de eso, use la etiqueta correcta para lo que quiera
hacer.</p>
<p>El proceso de conversión de DocBook a otros formatos como
HTML o Postscript garantiza que la presentación de todos
ellos será la misma.</p>
</li>
<li>
<p>Dejar de pensar en cómo representar la documentación
y concentrarse solamente en el contenido.</p>
<li>
<p>Como la documentación no está pensada para un
determinado formato de salida la misma documentación puede
crearse en diferentes formatos: texto, HTML, Postscript, RTF,
PDF, etc.</p></li>
<li>
<p>La documentación es más "inteligente", lo que
permite hacer cosas más inteligentes con ella. Por ejemplo,
es posible crear un índice automático que liste cada
comando mostrado en la documentación.</p>.</li>
</ul>
<p>Si está familiarizado con ellos es como las galerías
de estilo de Microsoft Word, sólo que infinitamente más
potente.</p>
<p>Por supuesto, esta potencia tiene un precio:</p>
<ul>
<li><p>Al existir un mayor número de etiquetas el aprendizaje
es más largo y cuesta más trabajo aprender a
usarlas.</p>
<p>La mejor manera de aprender es leer los fuentes de otros
documentos para ver cómo representaron información
similar otros autores.</p></li>
<li><p>El proceso de conversión no es tan simple.</p></li>
</ul>
<h2>¿Qué pasa si no sabe DocBook? ¿Todavía
puedo ayudar?</h2>
<p>Sí, por supuesto. Un poco de documentación es mejor
que no tener nada. Si tiene documentación con la que
contribuir y no está en formato DocBook no se preocupe.</p>
<p><a href="submitting.html">Envíe</a> la documentación
de la manera habitual. Algún miembro del proyecto
recogerá los documentos que envíe y trabajará
en ellos. Con un poco de suerte le enviarán una copia
ya etiquetada en DocBook. Así podrá comparar el
documento original con el que reciba y podrá ir aprendiendo
a hacerlo usted mismo.</p>
<p>Obviamente esto retrasa el que la documentación esté
online porque su documento requiere un trabajo adicional. Esto
puede suponer unas horas o unos días pero de cualquier modo
llegará a su destino.</p>
<h2>¿ Necesita má información sobre SGML y
DocBook?</h2>
<p>Lo primero que deberí leer es el <a
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/index.html">
<b>Documentation Project Primer</b></a>. Es una extensa
explicación de todo lo que necesita saber para poder trabajar
con la documentación de FreeBSD. Es un documento largo,
dividido en múltiples páginas diferentes de pequeño
tamaño. También puede verlo en formato de <a
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>un sola página</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>La web de SGML/XML. Incluye más recursos sobre 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>El "Gentle Introduction to SGML". De recomendada lectura para
cualquiera que desee tener conocimientos avanzados de SGML.</p></dd>
<dt><a
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
<dd><p>OASIS mantiene el DTD DocBook. Estas páginas
están pensadas para usuarios con bastante experiencia
con SGML y quieren aprender DocBook.</p>
</dd>
</dl>
<p></p><a href="docproj.html">Inicio del Proyecto de Documentación de FreeBSD</a>
&footer;
</body>
</html>
|
