/[gentoo]/xml/htdocs/doc/es/xml-guide.xml
Gentoo

Contents of /xml/htdocs/doc/es/xml-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.19 - (show annotations) (download) (as text)
Sat Feb 28 20:16:52 2009 UTC (11 years, 6 months ago) by chiguire
Branch: MAIN
Changes since 1.18: +11 -5 lines
File MIME type: application/xml
updated spanish translation (jose maria alonso)

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/es/xml-guide.xml,v 1.18 2008/05/03 11:28:58 chiguire Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/doc/es/xml-guide.xml" lang="es">
6 <title>Guía Gentoo de GuideXML</title>
7
8 <author title="Autor">
9 <mail link="neysx"/>
10 </author>
11 <author title="Autor">
12 <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
13 </author>
14 <author title="Author"><!-- zhen@gentoo.org -->
15 John P. Davis
16 </author>
17 <author title="Editor">
18 <mail link="peesh@gentoo.org">Jorge Paulo</mail>
19 </author>
20 <author title="Editor">
21 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22 </author>
23 <author title="Editor">
24 <mail link="nightmorph"/>
25 </author>
26 <author title="Traductor">
27 <mail link="chiguire@gentoo.org">John Christian Stoddart</mail>
28 </author>
29 <author title="Traductor">
30 <mail link="yoswink@gentoo.org">José Luis Rivero</mail>
31 </author>
32 <author title="Traductor">
33 <mail link="gentoo@nimiux.org">José María Alonso</mail>
34 </author>
35
36 <abstract>
37 Esta guía enseña cómo estructurar documentación para la web usando la
38 nueva sintaxis liviana Gentoo GuideXML. Esta sintaxis constituye el
39 formato oficial para la documentación del Gentoo, este mismo documento
40 fue creado usando GuideXML. Esta guía asume un conocimiento básico de
41 XML y HTML.
42 </abstract>
43
44 <!-- The content of this document is licensed under the CC-BY-SA license -->
45 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
46 <license/>
47
48 <version>10</version>
49 <date>2009-02-27</date>
50
51 <chapter>
52 <title>Fundamentos de GuideXML</title>
53 <section>
54 <title>Metas de GuideXML </title>
55 <body>
56
57 <p>
58 La sintaxis de GuideXML es sencilla pero expresiva, por eso es fácil
59 de aprender y al mismo tiempo proporciona todas las características
60 necesarias para la creación de documentación Web. El número de
61 etiquetas es muy pequeño -- solamente las necesarias. Esto hace muy
62 fácil la transformación de la guía a otros formatos, tales como
63 DocBook XML/SGML y páginas web (HTML).
64 </p>
65
66 <p>
67 El objetivo es facilitar la <e>creación</e> y <e>transformación</e> de
68 documentos guía, como este, en XML.
69 </p>
70 </body>
71 </section>
72
73 <section>
74 <title>Otros recursos</title>
75 <body>
76
77 <p>
78 Si planea contribuir a la documentación de Gentoo, o quiere probar la
79 GuideXML, por favor lea nuestra guía de <uri
80 link="http://www.gentoo.org/proj/es/gdp/doc/doc-tipsntricks.xml">Trucos
81 y Consejos</uri>, que contiene trucos y consejos para el desarrollo de
82 documentación.
83 </p>
84
85 <p>
86 Tal le interese mirar <uri link="?passthru=1">las fuentes XML</uri> de
87 este documento mientras lo lee.
88 </p>
89 </body>
90 </section>
91 </chapter>
92
93 <chapter>
94 <title>GuideXML</title>
95 <section>
96 <title>Estructura básica</title>
97 <body>
98
99 <p>
100 Vamos a comenzar con el aprendizaje de la sintaxis de GuideXML.
101 Comenzaremos con las etiquetas iniciales usadas en un documento de
102 guía en XML:
103 </p>
104
105 <pre caption="El comienzo de un documento de GuideXML">
106 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
107 &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
108 &lt;!-- &#36;Header&#36; --&gt;
109
110 &lt;guide link="<i>/doc/es/guia.xml</i>" lang="<i>es</i>"&gt;
111 &lt;title&gt;<i>Guía Gentoo de Documentación</i>&lt;/title&gt;
112
113 &lt;author title="<i>Autor</i>"&gt;
114 &lt;mail link="<i>nombre@gentoo.org</i>"&gt;<i>Su Nombre</i>&lt;/mail&gt;
115 &lt;/author&gt;
116
117 &lt;abstract&gt;
118 Esta guía enseña cómo estructurar documentación para la web usando la
119 nueva sintaxis liviana GuideXML de Gentoo. Esta sintaxis constituye el
120 formato oficial para la documentación de Gentoo, este mismo documento
121 fue creado usando GuideXML. Esta guía asume un conocimiento básico de
122 XML y HTML.
123 &lt;/abstract&gt;
124
125 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
126 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
127 &lt;license/&gt;
128
129 &lt;version&gt;<i>1.0</i>&lt;/version&gt;
130 &lt;date&gt;<i>2004-12-25</i>&lt;/date&gt;
131 </pre>
132
133 <p>
134 En las primeras líneas, encontramos la etiqueta necesaria que
135 identifica este documento como un documento XML y especifica su
136 DTD. La línea <c>&lt;!-- &#36;Header&#36; --&gt;</c> será modificada
137 automáticamente por el servidor CVS y sirve para llevar la cuenta de
138 las revisiones. Le sigue una etiqueta <c>&lt;guide&gt;</c> -- el
139 documento guía entero está encerrado entre etiquetas <c>&lt;guide&gt;
140 y &lt;/guide&gt;</c>. El atributo <c>link</c> es opcional y
141 preferiblemente debería contener el trayecto relativa a la raíz del
142 documento, aunque el nombre del archivo por sí solo también
143 funcionará. Solo se usa para generar un enlace a la versión "para
144 imprimir" del documento y para revisar si la traducción está
145 actualizada. Nuestro motor XSL pasa la trayectoria real a la hoja de
146 estilo XSL. El atributo del enlace solo se usa como valor por defecto
147 en caso que el XML sea procesado por otros medios.
148 <br/>
149 El atributo <c>lang</c> debe ser usado para especificar el código de
150 idioma del documento. Sirve para definir el formato de la fecha y para
151 traducir cadenas de caracteres como "<e>Note</e>", "<e>Content</e>",
152 etc. al lenguaje especificado. La opción por defecto es inglés.
153 </p>
154
155 <p>
156 Después, hay una etiqueta <c>&lt;title&gt;</c>, usada para colocar el
157 título del documento de la guía.
158 </p>
159
160 <p>
161 Luego, vienen las etiquetas <c>&lt;author&gt;</c>, que contienen
162 información sobre los autores del documento. Cada etiqueta
163 <c>&lt;author&gt;</c> permite un atributo opcional <c>title</c>, usado
164 para especificar la relación del autor con el documento (autor,
165 co-autor, editor, etc.). En este ejemplo en particular, los nombres de
166 los autores están encerrados en otra etiqueta -- una etiqueta
167 <c>&lt;mail&gt;</c>, usada para especificar una dirección email para
168 esta persona en particular. La etiqueta <c>&lt;mail&gt;</c> es
169 opcional y puede ser omitida, requiriéndose al menos un elemento
170 <c>&lt;author&gt;</c> por cada documento de guía.
171 </p>
172
173 <p>
174 Lo siguiente, llegamos a las etiquetas <c>&lt;abstract&gt;</c>,
175 <c>&lt;version&gt;</c> y <c>&lt;date&gt;</c>, usadas para especificar
176 un resumen del documento, la versión actual, y la fecha de la versión
177 (en formato YYYY-MM-DD) respectivamente. Fechas que no sean válidas o
178 que no estén en formato YYYY-MM-DD aparecerán textualmente en el nuevo
179 documento.
180 </p>
181
182 <p>
183 Esto es todo en cuanto a las etiquetas que deben aparecer al comienzo
184 del documento. Estas etiquetas, salvo <c>&lt;title&gt;</c> y
185 <c>&lt;mail&gt;</c>, no deberían aparecer en ningún otro lugar que no
186 sea inmediatamente dentro de la etiqueta <c>&lt;guide&gt;</c>, y por
187 consistencia, se recomienda (aunque no es obligatorio) que esas
188 etiquetas, aparezcan antes que el contenido del documento.
189 </p>
190
191 <p>
192 Finalmente encontramos la etiqueta <c>&lt;license/&gt;</c>, usada para
193 publicar el documento bajo la licencia <uri
194 link="http://creativecommons.org/licenses/by-sa/2.5/"> Creative
195 Commons - Attribution / Share Alike</uri> como se requiere en la <uri
196 link="/proj/es/gdp/doc/doc-policy.xml">Política de
197 documentación</uri>.
198 </p>
199 </body>
200 </section>
201
202 <section>
203 <title>Capítulos y secciones</title>
204 <body>
205
206 <p>
207 Una vez que las etiquetas iniciales han sido especificadas, estamos
208 listos para empezar a añadir los elementos estructurales del
209 documento. Los documentos de guía están divididos en capítulos, y cada
210 capítulo puede tener una o más secciones. Cada capítulo y cada sección
211 tiene su título. Aquí hay un capítulo de ejemplo con una sola sección,
212 consistente en un párrafo. Si agrega este XML al XML del <uri
213 link="#doc_pre2">ejemplo anterior</uri> y añade <c>&lt;/guide&gt;</c>
214 al final del fichero, tendrá un documento de guía válido (aunque
215 mínimo):
216 </p>
217
218 <pre caption="Ejemplo de guía mínima">
219 &lt;chapter&gt;
220 &lt;title&gt;<i>Este es mi capítulo</i>&lt;/title&gt;
221 &lt;section&gt;
222 &lt;title&gt;<i>Esta es una sección en uno de mis capítulos</i>&lt;/title&gt;
223 &lt;body&gt;
224
225 &lt;p&gt;
226 <i>Esto es texto contenido en mi sección .</i>
227 &lt;/p&gt;
228
229 &lt;/body&gt;
230 &lt;/section&gt;
231 &lt;/chapter&gt;
232 </pre>
233
234 <p>
235 Arriba, ajustamos el título del capítulo añadiendo un elemento hijo
236 <c>&lt;title&gt;</c> al elemento <c>&lt;chapter&gt;</c>. Luego,
237 creamos una sección añadiendo un elemento <c>&lt;section&gt;</c>. Si
238 observa en el interior del elemento <c>&lt;section&gt;</c>, verá que
239 contiene dos elementos hijos -- un elemento <c>&lt;title&gt;</c> y
240 otro <c>&lt;body&gt;</c>. Mientras que el elemento
241 <c>&lt;title&gt;</c> no es nada nuevo, el elemento <c>&lt;body&gt;</c>
242 sí lo es -- es el contenido de texto de esta sección. Veamos dentro de
243 poco qué etiquetas se permiten dentro de un elemento
244 <c>&lt;body&gt;</c>.
245 </p>
246
247 <note>Un elemento <c>&lt;guide&gt;</c> puede contener múltiples
248 capítulos (elementos <c>&lt;chapter&gt;</c>), y un elemento
249 <c>&lt;chapter&gt;</c> puede contener múltiples secciones (elementos
250 <c>&lt;section&gt;</c>). Sin embargo, un elemento
251 <c>&lt;section&gt;</c> sólo puede contener un único elemento
252 <c>&lt;body&gt;</c>.
253 </note>
254 </body>
255 </section>
256
257 <section>
258 <title>Un ejemplo de &lt;body&gt;</title>
259 <body>
260
261 <p>
262 Ahora, es el momento de aprender a maquetar los contenidos. Aquí está
263 el código XML de un ejemplo de un elemento <c>&lt;body&gt;</c>:
264 </p>
265
266 <pre caption="Ejemplo de un elemento body">
267 &lt;p&gt;
268 Esto es un párrafo. &lt;path&gt;/etc/passwd&lt;/path&gt; es un fichero.
269 &lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt; es mi sitio web favorito. Escriba &lt;c&gt;ls&lt;/c&gt; si lo desea. Yo &lt;e&gt;de veras&lt;/e&gt; quiero irme a dormir ahora.
270 &lt;/p&gt;
271
272 &lt;pre caption="Ejemplo de código"&gt;
273 Este es el texto de salida o código
274 # &lt;i&gt;esto es lo que escribe el usuario&lt;/i&gt;
275
276 Haz que el HTML/XML sea más fácil de leer usando énfasis selectivo:
277 &lt;foo&gt;&lt;i&gt;bar&lt;/i&gt;&lt;/foo&gt;
278
279 &lt;comment&gt;(Así se inserta una nota dentro de un bloque de código)&lt;/comment&gt;
280 &lt;/pre&gt;
281
282 &lt;note&gt;
283 Esto es una nota.
284 &lt;/note&gt;
285
286 &lt;warn&gt;
287 Esta es una advertencia.
288 &lt;/warn&gt;
289
290 &lt;impo&gt;
291 Esto es importante.
292 &lt;/impo&gt;
293 </pre>
294
295 <p>
296 Ahora, aquí se ve cómo se queda el elemento <c>&lt;body&gt;</c>
297 antes descrito:
298 </p>
299
300 <p>
301 Esto es un párrafo. <path>/etc/passwd</path> es un fichero.
302 <uri>http://forums.gentoo.org</uri> es mi sitio web favorito. Escriba
303 <c>ls</c> si lo quiere así. Yo <e>de veras</e> quiero irme a dormir
304 ahora.
305 </p>
306
307 <pre caption="Código de ejemplo">
308 Este es el texto de salida o código.
309 # <i>esto es lo que escribe el usuario</i>
310
311 Haz que el HTML/XML sea más fácil de leer usando énfasis selectivo:
312 &lt;foo&gt;<i>bar</i>&lt;/foo&gt;
313
314 <comment>(Así se inserta una nota dentro de un bloque de
315 código)</comment>
316 </pre>
317
318 <note>
319 Esto es una nota.
320 </note>
321
322 <warn>
323 Esta es una advertencia.
324 </warn>
325
326 <impo>
327 Esto es importante.
328 </impo>
329 </body>
330 </section>
331
332 <section>
333 <title>Las etiquetas &lt;body&gt;</title>
334 <body>
335
336 <p>
337 Hemos visto un montón de nuevas etiquetas en la sección anterior --
338 aquí está lo que necesita saber de ellas. Las etiquetas
339 <c>&lt;p&gt;</c> (párrafo), <c>&lt;pre&gt;</c> (bloque de código),
340 <c>&lt;note&gt;</c> (nota), <c>&lt;warn&gt;</c> (advertencia) y
341 <c>&lt;impo&gt;</c> (importante) todas pueden contener una o más
342 lineas de texto. Además, junto a los elementos <c>&lt;table&gt;</c>
343 (los cuales veremos después), son las únicas etiquetas que deben
344 aparecer inmediatamente dentro de un elemento <c>&lt;body&gt;</c>.
345 Otra cosa -- estas etiquetas <e>no deben</e> ser apiladas -- en otras
346 palabras, <e>no deben</e> apilarse, o sea, no ponga un elemento
347 <c>&lt;note&gt;</c> dentro de un elemento <c>&lt;p&gt;</c>. Como puede
348 imaginar, el elemento <c>&lt;pre&gt;</c> conserva los espacios en
349 blanco exactamente igual, haciéndolo adecuado para ejemplos de
350 código. Es obligatorio nombrar la etiqueta <c>&lt;pre&gt;</c> con un
351 atributo <c>caption</c>:
352 </p>
353
354 <pre caption="Poniendo un nombre a &lt;pre&gt;">
355 &lt;pre caption="Salida de uptime"&gt;
356 # &lt;i&gt;uptime&lt;/i&gt;
357 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
358 &lt;/pre&gt;
359 </pre>
360 </body>
361 </section>
362
363 <section>
364 <title>Epígrafes</title>
365 <body>
366
367 <p by="Estudiante anónimo">
368 Delegados de los 13 estados originales formaron el Congreso
369 Contento. Thomas Jefferson, un virgen y Benjamín Franklin fueron dos
370 de los cantantes de la Declaración de la Independencia. Franklin
371 descubrió la corriente eléctrica frotando dos gatos hacia atrás y
372 declaró "Un caballo dividido entre sí mismo no puede mantenerse de
373 pie." Franklin murió en 1790 y todavía lo está.
374 </p>
375
376 <p>
377 Los epígrafes son utilizados a veces al comienzo de algunos párrafos
378 para ilustrar lo que viene. Es sólo un párrafor con un atributo
379 <c>by</c> que contiene la firma.
380 </p>
381
382 <pre caption="Estudiante anónimo">
383 &lt;p by="Estudiante anónimo"&gt;
384 Delegados de los 13 estados originales formaron el ...
385 &lt;/p&gt;
386 </pre>
387 </body>
388 </section>
389
390 <section>
391 <title>&lt;path&gt;, &lt;c&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;</title>
392 <body>
393
394 <p>
395 Los elementos <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>,
396 <c>&lt;e&gt;</c>, <c>&lt;sub&gt;</c> y <c>&lt;sup&gt;</c> pueden ser
397 usados dentro de cualquier hijo de <c>&lt;body&gt;</c>, excepto dentro
398 del elemento <c>&lt;pre&gt;</c>.
399 </p>
400
401 <p>
402 Los elementos <c>&lt;path&gt;</c> se usan para marcar texto que hace
403 referencia a <e>ficheros en disco</e> -- tanto si es <e>una ruta
404 absoluta o relativa</e>, o si es simplemente un <e>nombre de
405 fichero</e>. Este elemento generalmente se muestra con una fuente
406 monoespaciada para diferenciarlo del tipo estándar del párrafo.
407 </p>
408
409 <p>
410 El elemento <c>&lt;c&gt;</c> se usa para marcar un <e>comando</e> o
411 <e>entrada del usuario</e>. Piense en <c>&lt;c&gt;</c> como un medio
412 de avisar al lector que pueden escribir algo o que realizarán en algún
413 tipo de acción. Por ejemplo, todos las etiquetas XML mostradas en este
414 documento, están encerradas entre etiquetas <c>&lt;c&gt;</c> porque
415 representan algo que el usuario podría escribir en algo que no es una
416 línea de comandos. Usando elementos <c>&lt;c&gt;</c>, ayudará a sus
417 lectores a que identifiquen rápidamente los comandos que necesitan
418 escribir. También porque los elementos <c>&lt;c&gt;</c> se diferencian
419 del texto normal, <e>casi no hará falta rodear la entrada del usuario
420 con dobles comillas</e>. Por ejemplo, no se refiera al elemento
421 "<c>&lt;c&gt;</c>" como aparece en esta frase. Evitar el uso
422 innecesario de dobles comillas hace que el documento sea más legible
423 -- ¡y adorable!
424 </p>
425
426 <p>
427 Tal como probablemente ha podido adivinar, la <c>&lt;b&gt;</c> se
428 utiliza para enfatizar con <b>negritas</b>.
429 </p>
430
431 <p>
432 <c>&lt;e&gt;</c> se usa para aplicar énfasis a una palabra o frase;
433 por ejemplo: Yo <e>realmente</e> debería usar puntos y comas más a
434 menudo. Como puede ver, este texto se distingue del párrafo normal con
435 el énfasis. Esto ayuda a hacer darle más <e>impacto</e> a su prosa.
436 </p>
437
438 <p>
439 Los elementos <c>&lt;sub&gt;</c> y <c>&lt;sup&gt;</c> se utilizan para
440 especificar <sub>subíndice</sub> y <sup>superíndices</sup>.
441 </p>
442 </body>
443 </section>
444
445 <section>
446 <title>Ejemplos de código y codificación con colores</title>
447 <body>
448
449 <p>
450 Para incrementar la legibilidad de ejemplos de código, se permite el
451 uso de las siguientes etiquetas dentro de bloques <c>&lt;pre&gt;</c>:
452 </p>
453
454 <dl>
455 <dt><c>&lt;i&gt;</c></dt>
456 <dd>Distingue la entrada del usuario del texto desplegado</dd>
457 <dt><c>&lt;comment&gt;</c></dt>
458 <dd>Comentarios relevantes a las acciones después del comentario</dd>
459 <dt><c>&lt;Palabra-clave&gt;</c></dt>
460 <dd>Denota una palabra-clave en el lenguaje utilizado en el ejemplo</dd>
461 <dt><c>&lt;ident&gt;</c></dt>
462 <dd>Usado para un identificador
463 </dd>
464 <dt><c>&lt;const&gt;</c></dt>
465 <dd>Usado para una constante
466 </dd>
467 <dt><c>&lt;stmt&gt;</c></dt>
468 <dd>Usado para un enunciado
469 </dd>
470 <dt><c>&lt;var&gt;</c></dt>
471 <dd>Usado para una variable
472 </dd>
473 </dl>
474
475 <note>
476 Recuerde que todos los espacios en blanco, antes y después y todos los
477 cortes de línea en bloques <c>&lt;pre&gt;</c> aparecerán tal cual en
478 la página html.
479 </note>
480
481 <p>
482 Ejemplo de un bloque <c>&lt;pre&gt;</c> codificado con colores:
483 </p>
484
485 <pre caption="My first ebuild">
486 <comment># Copyright 1999-2009 <b>Gentoo Foundation</b>
487 # Distributed under the terms of the GNU General Public License v2
488 # &#36;Header: $</comment>
489
490 <ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const>
491 <ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const>
492 <ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const>
493
494 <ident>LICENSE</ident>=<const>"GPL-2"</const>
495 <ident>SLOT</ident>=<const>"0"</const>
496 <ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const>
497 <ident>IUSE</ident>=<const>""</const>
498
499 <stmt>src_compile()</stmt> {
500 <keyword>econf</keyword> --with-posix-regex
501 <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const>
502 }
503
504 <stmt>src_install()</stmt> {
505 <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const>
506
507 <keyword>dodoc</keyword> FAQ NEWS README
508 <keyword>dohtml</keyword> EXTENDING.html ctags.html
509 }
510 </pre>
511 </body>
512 </section>
513
514 <section>
515 <title>&lt;mail&gt; and &lt;uri&gt;</title>
516 <body>
517
518 <p>
519 Anteriormente echamos un vistazo a la etiqueta <c>&lt;mail&gt;</c> ;
520 se usa para enlazar un texto con una dirección de corre electrónico, y
521 tiene la forma <c>&lt;mail link="foo.bar@example.com"&gt;Mr. Foo
522 Bar&lt;/mail&gt;</c>. Si desea mostrar la dirección de email, puede
523 usar <c>&lt;mail&gt;foo.bar@example.com&lt;/mail&gt;</c>, lo cual se
524 vería como <mail>foo.bar@example.com</mail>.
525 </p>
526
527 <p>
528 Las formas abreviadas facilitan el uso de nombres y direcciones de
529 correo de desarrolladores Gentoo. Ambas formas
530 <c>&lt;mail&gt;neysx&lt;/mail&gt;</c> y <c>&lt;mail
531 link="neysx"/&gt;</c> aparecerán como <mail>neysx</mail>. Si desea
532 usar un correo de un desarrollador Gentoo con un contenido distinto a
533 su nombre completo, use la segunda forma con algun contenido. Por
534 ejemplo, usar el primer nombre del desarrollador: <c>&lt;mail
535 link="neysx"&gt;Xavier&lt;/mail&gt;</c> aparece como <mail
536 link="neysx">Xavier</mail>.
537 <br/>
538 Esto es particularmente útil cuando quiere referirse a un
539 desarrollador cuyo nombre contiene caracteres "extraños" que no puede
540 escribir.
541 </p>
542
543 <p>
544 La etiqueta <c>&lt;uri&gt;</c> se usa para apuntar a
545 ficheros/localizaciones en Internet. Tiene dos formas -- la primera
546 puede usarse cuando se quiere tener la URI mostrada en el cuerpo del
547 texto, como en este enlace a <uri>http://forums.gentoo.org</uri>. Para
548 crear este enlace, escribí
549 <c>&lt;uri&gt;http://forums.gentoo.org&lt;/uri&gt;</c>. La forma
550 alternativa es cuando se quiere asociar una URI con otro texto -- por
551 ejemplo, <uri link="http://forums.gentoo.org">Foros de Gentoo</uri>.
552 Para crear <e>este</e> enlace, escribí <c>&lt;uri
553 link="http://forums.gentoo.org"&gt; Foros de
554 Gentoo&lt;/uri&gt;</c>. No necesita escribir
555 <c>http://www.gentoo.org/</c> para enlazar otras partes del sitio Web
556 de Gentoo. Por ejemplo, para enlazar al <uri link="/doc/en/">índice
557 principal de la documentación</uri> simplemente sería <c>&lt;uri
558 link="/doc/en/index.xml"&gt;índice principal de la
559 documentación&lt;/uri&gt;</c>. Hasta puede omitir <c>index.xml</c>
560 cuando apunte directamente al índice de un directorio, ejemplo:
561 <c>&lt;uri link="/doc/en/"&gt;índice principal de la
562 documentación&lt;/uri&gt;</c>. El dejar la barra final ahorra una
563 petición HTTP adicional.
564 </p>
565
566 <p>
567 No debe usar una etiqueta <c>&lt;uri&gt;</c> con un atributo
568 <c>link</c> que comienze con <c>mailto:</c>. En este caso, haga uso de
569 la etiqueta <c>&lt;mail&gt;</c>.
570 </p>
571
572 <p>
573 Por favor evite el síndrome de <uri
574 link="http://en.wikipedia.org/wiki/Click_here">haga click aquí</uri>
575 tal como nos recomienda el <uri
576 link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
577 </p>
578 </body>
579 </section>
580
581 <section>
582 <title>Ilustraciones</title>
583 <body>
584
585 <p>
586 Así se inserta una imagen en un documento -- <c>&lt;figure
587 link="mygfx.png" short="mi imagen" caption="mi imagen favorita de
588 todos los tiempos"/&gt;</c>. El atributo <c>link=</c> apunta a la
589 imagen, el atributo <c>short=</c> especifica una descripción corta
590 (actualmente usada para el atributo <c>alt=</c> de HTML), y una
591 leyenda. No es demasiado difícil :) También soportamos el estilo
592 estándar de HTML con la etiqueta &lt;img src="foo.gif"/&gt; para
593 añadir imágenes sin leyendas, bordes, etc.
594 </p>
595 </body>
596 </section>
597
598 <section>
599 <title>Tablas</title>
600 <body>
601
602 <p>
603 GuideXML soporta una sintaxis simplificada para tablas, similar al de
604 HTML. Para comenzar una tabla, use la etiqueta <c>&lt;table&gt;</c>.
605 Comience una hilera con una etiqueta <c>&lt;tr&gt;</c>. Sin embargo,
606 para los datos propios de la tabla, <e>no</e> soportamos el uso de la
607 etiqueta &lt;td&gt; de HTML; en cambio, use <c>&lt;th&gt;</c> para la
608 cabecera y <c>&lt;ti&gt;</c> si va a insertar un bloque de información
609 normal. Puede usar <c>&lt;th&gt;</c> en cualquier lugar donde se pueda
610 usar <c>&lt;ti&gt;</c> -- no hay obligación que los elementos
611 <c>&lt;th&gt;</c> aparezcan solo en la primera hilera.
612 </p>
613
614 <p>
615 Los encabezados de tabla (<c>&lt;th&gt;</c>) y los ítems de tabla
616 (<c>&lt;ti&gt;</c>) aceptan los atributos <c>colspan</c> y
617 <c>rowspan</c> para que su contenido abarque columnas, hileras o ambas
618 </p>
619
620 <p>
621 Además los ítems de tabla (<c>&lt;ti&gt;</c>) pueden alinearse a la
622 derecha, a la izquierda o centrados con el atributo <c>align</c>.
623 </p>
624
625 <table>
626 <tr>
627 <th align="center" colspan="4">Este titular abarca 4 columnas</th>
628 </tr>
629 <tr>
630 <th rowspan="6">Este título abarca 6 hileras</th>
631 <ti>Item A1</ti>
632 <ti>Item A2</ti>
633 <ti>Item A3</ti>
634 </tr>
635 <tr>
636 <ti align="center">Item B1</ti>
637 <th colspan="2" rowspan="2">Título en bloque 2x2</th>
638 </tr>
639 <tr>
640 <ti align="right">Item C1</ti>
641 </tr>
642 <tr>
643 <ti colspan="3" align="center">Item D1..D3</ti>
644 </tr>
645 <tr>
646 <ti rowspan="2">Item E1..F1</ti>
647 <ti colspan="2" align="right">Item E2..E3</ti>
648 </tr>
649 <tr>
650 <ti colspan="2" align="right">Item F2..F3</ti>
651 </tr>
652 </table>
653 </body>
654 </section>
655
656 <section>
657 <title>Listas</title>
658 <body>
659
660 <p>
661 Para crear listas, ordenadas o no, simplemente use las etiquetas
662 <c>&lt;ol&gt;</c>, <c>&lt;ul&gt;</c> y <c>&lt;li&gt;</c> al estilo
663 XHTML. Las listas solo deben aparecer dentro de las etiquetas
664 <c>&lt;body&gt;</c> y <c>&lt;li&gt;</c> lo cual significa que pueden
665 hacerse listas dentro de listas. No se olvide que está escribiendo XML
666 y que debe colocar las etiquetas de cierre, incluyendo ítems en listas,
667 a diferencia de HTML.
668 </p>
669
670 <p>
671 También soportamos listas de definiciones (<c>&lt;dl&gt;</c>). Por
672 favor note que ni la etiqueta de definición de término
673 (<c>&lt;dt&gt;</c>) ni la de definición de datos (<c>&lt;dd&gt;</c>)
674 aceptan etiquetas de otro nivel, como de párrafo o advertencia. Una
675 lista de definición se parece a esta:
676 </p>
677
678 <dl>
679 <dt><c>&lt;dl&gt;</c></dt>
680 <dd>A <b>D</b>efinición <b>E</b>tiqueta de lista, contiene</dd>
681 <dt><c>&lt;dt&gt;</c></dt>
682 <dd>Pares de <b>D</b>efinición <b>E</b>tiquetas de Términos</dd>
683 <dt><c>&lt;dd&gt;</c></dt>
684 <dd>y <b>E</b>tiquetas de <b>D</b>efinición de Datos</dd>
685 </dl>
686
687 <p>
688 La siguiente lista, copiada de <uri
689 link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri>
690 muestra que una lista de definición puede contener listas ordenadas y
691 sin orden, sin embargo, no puede contener otra lista de definición.
692 </p>
693
694 <dl>
695 <dt><b>The ingredients:</b></dt>
696 <dd>
697 <ul>
698 <li>100 g flour</li>
699 <li>10 g sugar</li>
700 <li>1 cup water</li>
701 <li>2 eggs</li>
702 <li>salt, pepper</li>
703 </ul>
704 </dd>
705 <dt><b>The procedure:</b></dt>
706 <dd>
707 <ol>
708 <li>Mix dry ingredients thoroughly</li>
709 <li>Pour in wet ingredients</li>
710 <li>Mix for 10 minutes</li>
711 <li>Bake for one hour at 300 degrees</li>
712 </ol>
713 </dd>
714 <dt><b>Notes:</b></dt>
715 <dd>The recipe may be improved by adding raisins</dd>
716 </dl>
717 </body>
718 </section>
719
720 <section>
721 <title>Referencias Internas en el Documento</title>
722 <body>
723
724 <p>
725 GuideXML hace que sea realmente sencillo referenciar a otras partes
726 del documento con hiperenlaces. Se puede crear un enlace que apunte al
727 <uri link="#doc_chap1">Capítulo Uno</uri> escribiendo <c>&lt;uri
728 link="#doc_chap1"&gt;Capítulo Uno&lt;/uri&gt;</c>. Para apuntar a <uri
729 link="#doc_chap1_sect2"> la sección dos del Capítulo Uno</uri>, se
730 escribe <c>&lt;uri link="#doc_chap1_sect2"&gt;la sección dos del
731 Capítulo Uno&lt;/uri&gt;</c>. Para hacer una referencia a la figura 3,
732 se escribe <c>&lt;uri link="doc_fig3"&gt;figura 3&lt;/uri&gt;</c>. O
733 para referirse al <uri link="#doc_pre2">listado de código 2 </uri>, se
734 escribe <c>&lt;uri link="doc_pre2"&gt;listado de código
735 2&lt;/uri&gt;</c>.
736 </p>
737
738 <p>
739 Sin embargo, algunas guías cambian a menudo y al emplear este 'conteo'
740 pueden producirse enlaces rotos. Para hacer frente a esto, se puede
741 definir un nombre para el <c>&lt;capítulo&gt;</c>,
742 <c>&lt;sección&gt;</c> o <c>&lt;tr&gt;</c> con el atributo <c>id</c> y
743 después apuntarlo así:
744 </p>
745
746 <pre caption="Utilizando el atributo id">
747 &lt;chapter id="foo"&gt;
748 &lt;title&gt;Esto es foo.&lt;/title&gt;
749 ...
750 &lt;p&gt;
751 Más información puede encontrarse en el &lt;uri link="#foo"&gt;capítulo foo&lt;/uri&gt;
752 &lt;/p&gt;
753 </pre>
754 </body>
755 </section>
756
757 <section>
758 <title>Renuncias de responsabilidad y documentos obsoletos</title>
759 <body>
760
761 <p>
762 El atributo <c>disclaimer</c> puede ser aplicado a guías y manuales
763 para desplegar un aviso predefinido de renuncia de responsabilidad al
764 comienzo del documento. Los textos de renuncia de responsabilidad
765 disponibles son:
766 </p>
767
768 <ul>
769 <li>
770 <b>articles</b> se utiliza para los <uri
771 link="/doc/en/articles/">artículos republicados</uri>
772 </li>
773 <li>
774 <b>draft</b> se utiliza para indicar que un documento está en fase
775 de redacción y que no debe considerarse oficial
776 </li>
777 <li>
778 <b>oldbook</b> se utiliza con manuales viejos para indicar que
779 están en desuso y que ya no son mantenidos
780 </li>
781 <li><b>obsolete</b> es utilizado para marcar un documento como
782 obsoleto.</li>
783 </ul>
784
785 <p>
786 Al marcar un documento como obsoleto, tal vez desee agregar un enlace
787 a una versión nueva. El atributo <c>redirect</c> hace justamente
788 eso. El usuario puede ser redirigido automáticamente a la página
789 nueva, pero no debe depender de este comportamiento.
790 </p>
791
792 <pre caption="Ejemplo de renuncia de responsabilidad">
793 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
794 &lt;!DOCTYPE guide SYSTEM "/dtd/guide.dtd"&gt;
795 &lt;!-- &#36;Header&#36; --&gt;
796
797 &lt;guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"&gt;
798 &lt;title>Gentoo x86 Installation Guide&lt;/title&gt;
799
800 &lt;author title="Author"&gt;
801 ...
802 </pre>
803 </body>
804 </section>
805
806 <section>
807 <title>FAQs</title>
808 <body>
809
810 <p>
811 Los documentos FAQ (preguntas de uso frecuente) necesitan comenzar con
812 una lista de preguntas enlazadas a sus respuestas. Se pierde mucho
813 tiempo creando este tipo de lista y se pueden cometer errores. Este
814 tipo de lista puede ser creada automáticamente si usa el elemento
815 <c>faqindex</c> como el primer capítulo del documento. Este elemento
816 tiene la misma estructura que un <c>chapter</c> y permite un texto
817 introductorio. Se espera que la estructura del documento se divida en
818 capítulos (al menos uno), que contenga secciones, cada sección con una
819 pregunta especificada en su elemento <c>title</c> y con la respuesta
820 en su <c>body</c>. El índice aparecerá como una sección por capítulo y
821 un enlace por pregunta.
822 </p>
823
824 <p>
825 Una mirada rápida a <uri link="/doc/es/faq.xml">FAQ</uri> y <uri
826 link="/doc/es/faq.xml?passthru=1">sus fuentes</uri> nos proporcionará
827 todas las explicaciones necesarias.
828 </p>
829 </body>
830 </section>
831 </chapter>
832
833 <chapter>
834 <title>Formato del Manual</title>
835 <section>
836 <title>Guide vs Book</title>
837 <body>
838
839 <p>
840 Para documentación de alto volument, como las <uri
841 link="/doc/es/handbook/handbook-x86.xml?part=1">Instrucciones de
842 Instalación</uri> se necesitaba un formato más amplio. Diseñamos unas
843 mejoras compatibles con GuideXML que nos permiten escribir
844 documentación modular y multi-página.
845 </p>
846 </body>
847 </section>
848
849 <section>
850 <title>Archivo principal</title>
851 <body>
852
853 <p>
854 El primer cambio responde a la necesidad de un documento
855 "maestro". Este documento realmente no comprende verdadero contenido,
856 sino enlaces a los módulos individuales del documento. La sintaxis no
857 difiere mucho de GuideXML:
858 </p>
859
860 <pre caption="Ejemplo del uso de book">
861 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
862 &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
863 &lt;!-- &#36;Header&#36; --&gt;
864
865 &lt;<i>book</i>&gt;
866 &lt;title&gt;Example Book Usage&lt;/title&gt;
867
868 &lt;author...&gt;
869 ...
870 &lt;/author&gt;
871
872 &lt;abstract&gt;
873 ...
874 &lt;/abstract&gt;
875
876 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
877 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
878 &lt;license/&gt;
879
880 &lt;version&gt;...&lt;/version&gt;
881 &lt;date&gt;...&lt;/date&gt;
882 </pre>
883
884 <p>
885 Por los momentos no se ven diferencias sustanciales (excepto por la
886 etiqueta <c>&lt;book&gt;</c> en vez de <c>&lt;guide&gt;</c>). En vez
887 de comenzar con los <c>&lt;chapter&gt;</c>s (capítulos) individuales,
888 definimos un <c>&lt;part&gt;</c>, el cual equivale a una parte
889 separada de un libro:
890 </p>
891
892 <pre caption="Definiendo una parte">
893 &lt;part&gt;
894 &lt;title&gt;Part One&lt;/title&gt;
895 &lt;abstract&gt;
896 ...
897 &lt;/abstract&gt;
898
899 <comment>(Definiendo varios capítulos)</comment>
900 &lt;/part&gt;
901 </pre>
902
903 <p>
904 Cada "part" se acompaña de un <c>&lt;title&gt;</c> y un resumen
905 (<c>&lt;abstract&gt;</c>) que proporciona una introducción resumida a
906 la parte.
907 </p>
908
909 <p>
910 Dentro de cada parte, definimos los capítulos individuales
911 (<c>&lt;chapter&gt;</c>s). Cada capítulo <e>debe</e> ser un documento
912 separado. Como resultado, no es de sorprenderse que podamos agregar
913 una etiqueta especial (<c>&lt;include&gt;</c>) para permitir la
914 inclusión del documento separado.
915 </p>
916
917 <pre caption="Definiendo un capítulo">
918 &lt;chapter&gt;
919 &lt;title&gt;Chapter One&lt;/title&gt;
920
921 &lt;include href="path/to/chapter-one.xml"/&gt;
922
923 &lt;/chapter&gt;
924 </pre>
925 </body>
926 </section>
927
928 <section>
929 <title>Diseñando los capítulos individuales</title>
930 <body>
931
932 <p>
933 El contenido de un capítulo individual se estructura de la siguiente
934 manera:
935 </p>
936
937 <pre caption="Sintaxis de un capítulo">
938 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
939 &lt;!DOCTYPE sections SYSTEM "/dtd/book.dtd"&gt;
940 &lt;!-- &#36;Header&#36; --&gt;
941
942 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
943 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
944
945 &lt;sections&gt;
946
947 &lt;abstract&gt;
948 This is a small explanation on chapter one.
949 &lt;/abstract&gt;
950
951 &lt;version&gt;...&lt;/version&gt;
952 &lt;date&gt;...&lt;/date&gt;
953
954 <comment>(Defina varias &lt;section&gt;s &lt;subsection&gt;s)</comment>
955
956 &lt;/sections&gt;
957 </pre>
958
959 <p>
960 En cada capítulo se pueden definir secciones (<c>&lt;section&gt;</c>s)
961 que equivale a un capítulo (<c>&lt;chapter&gt;</c>) en una Guía y
962 subsecciones (<c>&lt;subsection&gt;</c>s), que equivalen a una sección
963 (<c>&lt;section&gt;</c>) en una Guía.
964 </p>
965
966 <p>
967 Cada capítulo individual debe tener sus propios elementos para fecha y
968 versión. La última fecha de todos los capítulos y documento maestro
969 será desplegada cuando un usuario consult las distintas partes del
970 libro.
971 </p>
972 </body>
973 </section>
974 </chapter>
975
976 <chapter>
977 <title>Características avanzadas del manual</title>
978 <section>
979 <title>Valores globales</title>
980 <body>
981
982 <p>
983 A veces se repiten los mismos valores una y otra vez a través del
984 manual. Una operación global de búsqueda y reemplazo podría pasar algo
985 por alto o introducir cambios no deseados. Además, puede ser útil
986 definir diferentes valores a ser usados en capítulos compartidos,
987 dependiendo de cual manual incluya el capítulo.
988 </p>
989
990 <p>
991 Los valores globales pueden ser definidos en el archivos maestro del
992 manual y usados en todos los capítulos incluidos.
993 </p>
994
995 <p>
996 Para definir valores globales, agregue el elemento
997 <c>&lt;values&gt;</c> al archivo maestro del manual. Cada valor es
998 definido con un elemento <c>&lt;key&gt;</c> cuyo atributo <c>id</c>
999 identifica el valor, o sea, el nombre de la variable. El contenido de
1000 <c>&lt;key&gt;</c> corresponde a su valor.
1001 </p>
1002
1003 <p>
1004 El siguiente ejemplo define tres valores en un archivo maestro de un
1005 manual:
1006 </p>
1007
1008 <pre caption="Definir valores en un manual">
1009 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
1010 &lt;!DOCTYPE book SYSTEM "/dtd/book.dtd"&gt;
1011 &lt;!-- &#36;Header&#36; --&gt;
1012
1013 &lt;book&gt;
1014 &lt;title&gt;Example Book Usage&lt;/title&gt;
1015
1016 <i>&lt;values>
1017 &lt;key id="arch"&gt;x86&lt;/key&gt;
1018 &lt;key id="min-cd-name"&gt;install-x86-minimal-2007.0-r1.iso&lt;/key&gt;
1019 &lt;key id="min-cd-size"&gt;57&lt;/key&gt;
1020 &lt;/values&gt;</i>
1021
1022 &lt;author...&gt;
1023 ...
1024 &lt;/author&gt;
1025
1026 ...
1027 </pre>
1028
1029 <p>
1030 Los valores definidos pueden entonces ser usados a través del manual
1031 con el elemento <c>&lt;keyval id="key_id"/&gt;</c>. Especifique el
1032 nombre de la clave (key) en su atributo <c>id</c>, por lo que
1033 &lt;keyval id="min-cd-name"/&gt; sería reemplazado por
1034 "install-x86-minimal-2007.0-r1.iso" en el ejemplo.
1035 </p>
1036
1037 <pre caption="Usando valores definidos">
1038 &lt;p&gt;
1039 The Minimal Installation CD is called &lt;c&gt;<i>&lt;keyval id="min-cd-name"/&gt;</i>&lt;/c&gt;
1040 and takes up only <i>&lt;keyval id="min-cd-size"/&gt;</i> MB of diskspace. You can use this
1041 Installation CD to install Gentoo, but &lt;e&gt;only&lt;/e&gt; with a working Internet
1042 connection.
1043 &lt;/p&gt;
1044 </pre>
1045
1046 <p>
1047 Para facilitarle la vida a nuestros traductores, use solo valores que
1048 no requieran traducción. Por ejemplo, definimos el valor de
1049 <c>min-cd-size</c> como <c>57</c> y no <c>57 MB</c>.
1050 </p>
1051 </body>
1052 </section>
1053
1054 <section>
1055 <title>Elementos condicionales</title>
1056 <body>
1057
1058 <p>
1059 Los capítulos compartidos por varios manuales, tales como nuestro <uri
1060 link="/doc/es/handbook/">Manuales de Instalación</uri> frecuentemente
1061 tienen pequeñas diferencias, dependiendo de cuál manual los incluy. En
1062 vez de agregar contenido que sea irrelevante a algunos manuales, los
1063 autores pueden agregar una condición a los siguientes elementos:
1064 <c>&lt;section&gt;</c>, <c>&lt;subsection&gt;</c>,
1065 <c>&lt;body&gt;</c>, <c>&lt;note&gt;</c>, <c>&lt;impo&gt;</c>,
1066 <c>&lt;warn&gt;</c>, <c>&lt;pre&gt;</c>, <c>&lt;p&gt;</c>,
1067 <c>&lt;table&gt;</c>, <c>&lt;tr&gt;</c>, <c>&lt;ul&gt;</c>,
1068 <c>&lt;ol&gt;</c> y <c>&lt;li&gt;</c>.
1069 </p>
1070
1071 <p>
1072 La condición debe ser una expresión <uri
1073 link="http://es.wikipedia.org/wiki/XPath">Xpath</uri> que será
1074 evaluada al transformar el XML. Si evalúa a <c>true</c>, este elemento
1075 es procesado, si no, es ignorado. La condición es especificada en un
1076 atributo <c>test</c>.
1077 </p>
1078
1079 <p>
1080 El siguiente ejemplo usa el valor <c>arch</c>, el cual es definido en
1081 cada archivo maestro de manual para condicionar el contenido:
1082 </p>
1083
1084 <pre caption="Usando elementos condicionales">
1085 &lt;body test="contains('AMD64 x86',func:keyval('arch'))"&gt;
1086
1087 &lt;p&gt;
1088 Este párrafo aplica a ambas plataformas, x86 y AMD64.
1089 &lt;/p&gt;
1090
1091 &lt;p test="func:keyval('arch')='x86'"&gt;
1092 Este párrafo aplica solo a la plataforma x86.
1093 &lt;/p&gt;
1094
1095 &lt;p test="func:keyval('arch')='AMD64'"&gt;
1096 Este párrafo aplica solo a la plataforma AMD64.
1097 &lt;/p&gt;
1098
1099 &lt;p test="func:keyval('arch')='PPC'"&gt;
1100 ¡Este párrafo no será visto nunca!
1101 El boy entero es ignorado dada la primera condición.
1102 &lt;/p&gt;
1103
1104 &lt;/body&gt;
1105
1106 &lt;body test="contains('AMD64 PPC64',func:keyval('arch'))"&gt;
1107
1108 &lt;p&gt;
1109 Este párrafo aplica a las plataformas AMD64, PPC64 <comment>y PPC</comment> porque la cadena 'AMD64 PPC64' contiene 'PPC'.
1110 &lt;/p&gt;
1111
1112 &lt;note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"&gt;
1113 Esta nota solo aplica a las plataformas AMD64 y PPC64.
1114 &lt;/note&gt;
1115
1116 &lt;/body&gt;
1117 </pre>
1118 </body>
1119 </section>
1120 </chapter>
1121
1122 <chapter>
1123 <title>Estilo de codificación</title>
1124 <section>
1125 <title>Introducción</title>
1126 <body>
1127
1128 <p>
1129 Puesto que toda la documentación de Gentoo es esfuerzo conjunto y
1130 probablemente varias personas cambiarán la documentación existente, es
1131 necesario un estilo de codificación. Un estilo de codificación abarca
1132 dos secciones. La primera es relativa a la codificación interna - como
1133 se sitúan las etiquetas XML. La segunda trata sobre el contenido -
1134 como no confundir al lector.
1135 </p>
1136
1137 <p>
1138 Ambas secciones se describen a continuación.
1139 </p>
1140 </body>
1141 </section>
1142
1143 <section>
1144 <title>Estilo de codificación interno</title>
1145 <body>
1146
1147 <p>
1148 Los <b>fines de línea</b> deben ponerse inmediatamente después de
1149 <e>cada</e> etiqueta GuideXML (tanto de apertura como de cierre)
1150 exceptuando: <c>&lt;version&gt;</c>, <c>&lt;date&gt;</c>,
1151 <c>&lt;title&gt;</c>, <c>&lt;th&gt;</c>, <c>&lt;ti&gt;</c>,
1152 <c>&lt;li&gt;</c>, <c>&lt;i&gt;</c>, <c>&lt;e&gt;</c>,
1153 <c>&lt;uri&gt;</c>, <c>&lt;path&gt;</c>, <c>&lt;b&gt;</c>,
1154 <c>&lt;c&gt;</c>, <c>&lt;comment&gt;</c>, <c>&lt;mail&gt;</c>.
1155 </p>
1156
1157 <p>
1158 Deben situarse <b>líneas en blanco</b> inmediatamente después de
1159 <e>cada</e> <c>&lt;body&gt;</c> (sólo de apertura) y antes de
1160 <e>cada</e> <c>&lt;chapter&gt;</c>, <c>&lt;p&gt;</c>,
1161 <c>&lt;table&gt;</c>, <c>&lt;author&gt;</c> (conjunto),
1162 <c>&lt;pre&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>,
1163 <c>&lt;warn&gt;</c>, <c>&lt;note&gt;</c> e <c>&lt;impo&gt;</c>
1164 (solamente de apertura).
1165 </p>
1166
1167 <p>
1168 Los <b>ajustes de líneas</b> (word wrap) deben ser aplicados a los 80
1169 caracteres, excepto dentro de <c>&lt;pre&gt;</c>. Solamente se puede
1170 desviar de esta regla cuando no hay otra opción (por ejemplo cuando
1171 una URL excede el máximo de caracteres). El editor debe entonces
1172 ajustar la línea en cuanto exista el primer espacio en blanco. Debe
1173 intentar mantenerse el contenido <e>desplegado</e> de los elementos
1174 <c>&lt;pre&gt;</c> dentro de 80 columnas para ayudar a los usuarios de
1175 consola.
1176 </p>
1177
1178 <p>
1179 No debemos usar <b>sangrías</b>, excepto con las estructuras XML cuyas
1180 etiquetas padres sean <c>&lt;tr&gt;</c> (procedente de
1181 <c>&lt;table&gt;</c>), <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>
1182 <c>&lt;dl&gt;</c> y <c>&lt;author&gt;</c>. Si se usan sangrados, estos
1183 <e>obligatoriamente</e> debe ser de dos espacios por cada paso de
1184 sangrado. Esto significa que <e>nada</e> de tabs <e>ni</e> de más (de
1185 dos) espacios. Dicho sea de paso, que las tabulaciones no están
1186 permitidas en los documentos GuideXML.
1187 </p>
1188
1189 <p>
1190 En caso de tener que ajustar las líneas con construcciones de tipo
1191 <c>&lt;ti&gt;</c>, <c>&lt;th&gt;</c>, <c>&lt;li&gt;</c> o
1192 <c>&lt;dd&gt;</c>, debe usarse el sangrado para el contenido.
1193 </p>
1194
1195 <p>
1196 Un ejemplo de sangrado sería:
1197 </p>
1198
1199 <pre caption = "Ejemplo de sangrado">
1200 &lt;table&gt;
1201 &lt;tr&gt;
1202 &lt;th&gt;Foo&lt;/th&gt;
1203 &lt;th&gt;Bar&lt;/th&gt;
1204 &lt;/tr&gt;
1205 &lt;tr&gt;
1206 &lt;ti&gt;Esto es un ejemplo de sangrado.&lt;/ti&gt;
1207 &lt;ti&gt;
1208 En caso de que el texto no pueda ser mostrado en los 80 caracteres de
1209 ancho de línea, deberá usar el sangrado si la etiqueta padre lo permite.
1210 &lt;/ti&gt;
1211 &lt;/tr&gt;
1212 &lt;/table&gt;
1213
1214 &lt;ul&gt;
1215 &lt;li&gt;Primera opción&lt;/li&gt;
1216 &lt;li&gt;Segunda opción&lt;/li&gt;
1217 &lt;/ul&gt;
1218 </pre>
1219
1220 <p>
1221 Los <b>atributos</b> no deben tener espacios entre sí, el signo
1222 &quot;=&quot; y el valor del atributo. Como en el ejemplo:
1223 </p>
1224
1225 <pre caption="Atributos">
1226 <comment>Incorrecto :</comment> &lt;pre caption = "Atributos"&gt;
1227 <comment>Correcto:</comment> &lt;pre caption="Atributos"&gt;
1228 </pre>
1229 </body>
1230 </section>
1231
1232 <section>
1233 <title>Estilo de codificación externa</title>
1234 <body>
1235
1236 <p>
1237 Dentro de las tablas (<c>&lt;table&gt;</c>) y los listados
1238 (<c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c>) y <c>&lt;dl&gt;</c>, no deben
1239 usarse puntos finales (&quot;.&quot;) a menos que se usen varias
1240 oraciones. En ese caso, cada oración debería acabar en un punto (u
1241 otras marcas de puntuación).
1242 </p>
1243
1244 <p>
1245 Cada oración, incluyendo aquellas dentro de tablas y listados, debe
1246 empezar por una letra mayúscula.
1247 </p>
1248
1249 <pre caption="Puntos y letras mayúsculas">
1250 &lt;ul&gt;
1251 &lt;li&gt;Sin punto&lt;/li&gt;
1252 &lt;li&gt;Con punto. Varias oraciones, recuerda?&lt;/li&gt;
1253 &lt;/ul&gt;
1254 </pre>
1255
1256 <p>
1257 Los listados de código deben tener <e>siempre</e> una <c>leyenda</c>
1258 </p>
1259
1260 <p>
1261 Intente utilizar <c>&lt;uri&gt;</c> con el atributo <c>link</c> tanto
1262 como sea posible. En otras palabras, los <uri
1263 link="http://forums.gentoo.org">Foros de Gentoo</uri> se prefiere
1264 en vez de <uri>http://forums.gentoo.org</uri>.
1265 </p>
1266
1267 <p>
1268 Cuando comente algo dentro de una construcción <c>&lt;pre&gt;</c>,
1269 utilice <c>&lt;comment&gt;</c> y ponga entre paréntesis el comentario
1270 o la marca de comentario para el lenguaje que se utiliza (<c>#</c> si
1271 es para guiones bash y muchas otras cosas, <c>//</c> si es código C,
1272 etc.) Además sitúe el comentario <e>antes</e> del tema del comentario.
1273 </p>
1274
1275 <pre caption="Ejemplo de comentario">
1276 <comment>(Sustituye "john" por tu nombre de usuario)</comment>
1277 # <i>id john</i>
1278 </pre>
1279 </body>
1280 </section>
1281 </chapter>
1282
1283 <chapter>
1284 <title>Recursos</title>
1285 <section>
1286 <title>Comience a escribir</title>
1287 <body>
1288
1289 <p>
1290 Esta guía ha sido diseñada especialmente para ser "clara y directa"
1291 para que los desarrolladores puedan pasar más tiempo escribiendo
1292 documentación y menos tiempo aprendiendo la sintaxis XML. Esperamos
1293 que esto permitirá a los desarrolladores que no son muy conocedores de
1294 la documentación, comenzar a escribir documentación Gentoo de gran
1295 calidad. Quizá esté interesado en nuestra página de <uri
1296 link="/proj/es/gdp/doc/doc-tipsntricks.xml">Trucos y consejos sobre
1297 Documentación de Desarrollo</uri>. Si quiere ayudar (o tiene alguna
1298 duda sobre la guía), por favor mande un mensaje a la <mail
1299 link="gentoo-doc@gentoo.org">lista de correo gentoo-doc</mail>
1300 comentando lo que le gustaría saborear. ¡Diviértase!
1301 </p>
1302 </body>
1303 </section>
1304 </chapter>
1305 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20