/usr/share/help/es/gtk-doc-manual/index.docbook is in gtk-doc-tools 1.27-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 | <?xml version="1.0" encoding="utf-8" standalone="no"?>
<?xml-stylesheet type="text/xml" href="params.xsl"?>
<!-- vim: set ai tw=80 ts=3 sw=3: -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY FDL SYSTEM "fdl-appendix.xml">
<!ENTITY FDLlink "<link linkend='fdl'>included</link>">
]>
<!-- =============Document Header ============================= -->
<book id="index" lang="es">
<bookinfo>
<title>Manual de GTK-Doc</title>
<edition>1.24.1</edition>
<abstract role="description"><para>Manual del usuario para desarrolladores con instrucciones del uso de GTK-Doc.</para></abstract>
<authorgroup>
<author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> <address> <email>chris@wilddev.net</email> </address> </affiliation></author>
<author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> <email>d-mueth@uchicago.edu</email> </address> </affiliation></author>
<author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
</authorgroup>
<publisher role="maintainer"><publishername>Proyecto GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
<copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
<!-- translators: uncomment this:
<copyright>
<year>2000</year>
<holder>ME-THE-TRANSLATOR (Latin translation)</holder>
</copyright>
-->
<legalnotice>
<para>Se concede autorización para copiar, distribuir o modificar este documento según los términos de la <citetitle>GNU Free Documentation License</citetitle>, Versión 1.1, o cualquier otra versión posterior publicada por Free Software Foundation sin secciones invariables, textos de portada ni textos de contraportada. Se <link linkend="fdl">incluye</link> una copia de la licencia.</para>
<para>Muchos de los nombres usados por compañías para distinguir sus productos y servicios se mencionan como marcas comerciales. Donde aparezcan dichos nombres en cualquier documentación GNOME, y para que los miembros del proyecto de documentación las reconozcan dichas marcas comerciales, dichos nombres se imprimen en mayúsculas o iniciales mayúsculas.</para>
</legalnotice>
<revhistory>
<revision>
<revnumber>1.27</revnumber>
<date>07 Dec 2017</date>
<authorinitials>ss</authorinitials>
<revremark>fine tuning of the python port</revremark>
</revision>
<revision><revnumber>1.26</revnumber> <date>11 de agosto de 2017</date> <authorinitials>ss</authorinitials> <revremark>portar todas las herramientas de perl/bash a python</revremark></revision>
<revision><revnumber>1.25</revnumber> <date>21 de marzo de 2016</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, limpieza</revremark></revision>
<revision><revnumber>1.24</revnumber> <date>29 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.23</revnumber> <date>17 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.22</revnumber> <date>7 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, eliminadas funcionalidades obsoletas</revremark></revision>
<revision><revnumber>1.21</revnumber> <date>17 de julio de 2014</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, eliminadas funcionalidades obsoletas</revremark></revision>
<revision><revnumber>1.20</revnumber> <date>16 de febrero de 2014</date> <authorinitials>ss</authorinitials> <revremark>errores corregidos, soporte de marcado, mejoras en los estilos</revremark></revision>
<revision><revnumber>1.19</revnumber> <date>05 de junio de 2013</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.18</revnumber> <date>14 de septiembre de 2011</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, mejoras en la velocidad y soporte de marcado</revremark></revision>
<revision><revnumber>1.17</revnumber> <date>26 de febrero de 2011</date> <authorinitials>sk</authorinitials> <revremark>actualización urgente de corrección de error</revremark></revision>
<revision><revnumber>1.16</revnumber> <date>14 de enero de 2011</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y mejoras en la distribución</revremark></revision>
<revision><revnumber>1.15</revnumber> <date>21 de mayo de 2010</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y regresiones</revremark></revision>
<revision><revnumber>1.14</revnumber> <date>28 de marzo de 2010</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y mejoras en el rendimiento</revremark></revision>
<revision><revnumber>1.13</revnumber> <date>18 de diciembre de 2009</date> <authorinitials>sk</authorinitials> <revremark>actualización del tarball roto</revremark></revision>
<revision><revnumber>1.12</revnumber> <date>18 de diciembre de 2009</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y nuevas características</revremark></revision>
<revision><revnumber>1.11</revnumber> <date>16 de noviembre de 2008</date> <authorinitials>mal</authorinitials> <revremark>Migración a GNOME doc-utils</revremark></revision>
</revhistory>
<othercredit class="translator">
<personname>
<firstname>Daniel Mustieles</firstname>
</personname>
<email>daniel.mustieles@gmail.com</email>
</othercredit>
<copyright>
<year>2009 - 2017</year>
<holder>Daniel Mustieles</holder>
</copyright>
<othercredit class="translator">
<personname>
<firstname>Jorge González</firstname>
</personname>
<email>jorgegonz@svn.gnome.org</email>
</othercredit>
<copyright>
<year>2009 - 2011</year>
<holder>Jorge González</holder>
</copyright>
<othercredit class="translator">
<personname>
<firstname>Francisco Javier F. Serrador</firstname>
</personname>
<email>serrrador@svn.gnome.org</email>
</othercredit>
<copyright>
<year>2009</year>
<year>2010</year>
<holder>Francisco Javier F. Serrador</holder>
</copyright>
</bookinfo>
<!-- ======== Chapter 1: Introduction ======================== -->
<chapter id="introduction">
<title>Introducción</title>
<para>Este capítulo introduce GTK-Doc y proporciona una visión general de lo que es y cómo usarlo.</para>
<sect1 id="whatisgtkdoc">
<title>¿Qué es GTK-Doc?</title>
<para>GTK-Doc se usa para documentar código C. Generalmente se usa para documentar la API pública de bibliotecas, tales como las bibliotecas GTK+ y de GNOME. Pero también se puede usar para documentar código de aplicaciones.</para>
</sect1>
<sect1 id="howdoesgtkdocwork">
<title>¿Cómo funciona GTK-Doc?</title>
<para>GTK-Doc funciona usando documentación de las funciones ubicadas dentro de los archivos de fuentes en bloques de comentarios especialmente formateados, o documentación añadida a los archivos de plantillas que GTK-Doc usa (aunque debe notar que GTK-Doc sólo documentará las funciones declaradas en los archivos de cabecera; no produce salida para funciones estáticas).</para>
<para>GTK-Doc consiste en un número de scripts en python, cada uno realiza un paso diferente en el proceso.</para>
<para>Existen 5 pasos importantes en el proceso:</para>
<orderedlist>
<listitem>
<para><guilabel>Escribir la documentación.</guilabel> El autor rellena los archivos de fuentes con la documentación para cada función, macro, unión, etc. (En el pasado la información se introducía en archivos de plantillas, lo que ya no se recomienda).</para>
</listitem>
<listitem>
<para><guilabel>Obtener información acerca del código</guilabel>. <application>gtkdoc-scan</application> analiza los archivos de cabecera del código buscando declaraciones de funciones, macros, enumeraciones, estructuras y uniones. Crea el archivo <filename><module>-decl-list.txt</filename> que contiene una lista de las declaraciones, ubicándolas en secciones de acuerdo con el archivo de cabecera en el que están. Durante la primera ejecución este archivo se copia en <filename><module>-sections.txt</filename>. El autor puede reordenar las secciones y el orden de las declaraciones en ellas, para producir la salida que quiere. El segundo archivo que genera es <filename><module>-decl.txt</filename>. Este archivo contiene las declaraciones completas que encontró el análisis. Si por alguna razón quisiese que algunos símbolos apareciesen en los documentos, donde el análisis no puede encontrar la declaración completa o la declaración debería aparecer de forma diferente, puede introducir entradas de forma similar a las que hay en <filename><module>-decl.txt</filename> dentro de <filename><module>-overrides.txt</filename>.</para>
<para><application>gtkdoc-scangobj</application> también se puede usar para consultar dinámicamente una biblioteca sobre cualquiera de las subclases GObject que exporta. Guarda información sobre la posición de cada objeto en la jerarquía de clases y sobre cualquier propiedad de GObject y las señales que proporciona.</para>
<para><application>gtkdoc-scanobj</application> no se debería usar más. Se necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+.</para>
</listitem>
<listitem>
<para><guilabel>Generar el XML y el HTML/PDF.</guilabel><application>gtkdoc-mkdb</application> convierte los archivos de plantilla en archivos SGML o XML en la subcarpeta <filename class="directory">xml/</filename>. Si el código fuente contiene documentación de funciones, usando los bloques especiales de comentarios, entonces se mezclarán aquí. Si no se usan archivos tmpl sólo obtiene los documentos de los fuentes y los datos obtenidos en introspección.</para>
<para><application>gtkdoc-mkhtml</application> convierte los archivos XML en archivos HTML en la subcarpeta <filename class="directory">html/</filename>. De la misma forma <application>gtkdoc-mkpdf</application> convierte los archivos XML en un documento PDF llamado <filename><paquete>.pdf</filename>.</para>
<para>Los archivos en las carpetas <filename class="directory">xml/</filename> y <filename class="directory">html/</filename> y siempre se sobrescriben. Nunca se deben editar directamente.</para>
</listitem>
<listitem>
<para><guilabel>Arreglar referencias cruzadas entre documentos.</guilabel> Después de instalar los archivos HTML se puede ejecutar <application>gtkdoc-fixxref</application> para arreglar cualquier referencia cruzada entre documentos separados. Por ejemplo, la documentación GTK+ contiene muchas referencias cruzadas a tipos documentados en el manual de GLib. Al crear los archivadores «tarball» para su distribución, <application>gtkdoc-rebase</application> convierte todos los enlaces externos en enlaces web. Al instalar la documentación distribuida (pregenerada) la misma aplicación intentará convertir de nuevo los enlaces, esta vez a enlaces locales (donde esa documentación está instalada).</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="gettinggtkdoc">
<title>Obtener GTK-Doc</title>
<sect2 id="requirements">
<title>Requerimientos</title>
<para><guilabel>python 2/3</guilabel> - los scripts principales están escritos en python.</para>
<para><guilabel>xsltproc</guilabel>: el procesador xslt de libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
<para><guilabel>docbook-xsl</guilabel>: las hojas de estilo XLS de docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
<para>Una de <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> o <guilabel>vim</guilabel>: opcional, usada para el resaltado de sintaxis de los ejemplos.</para>
</sect2>
</sect1>
<sect1 id="aboutgtkdoc">
<title>Acerca de GTK-Doc</title>
<para>(ARRÉGLAME)</para>
<para>(Historia, autores, páginas web, listas de correo, licencias, planes futuros, comparación con otros sistemas similares.)</para>
</sect1>
<sect1 id="aboutthismanual">
<title>Acerca de este manual</title>
<para>(ARRÉGLAME)</para>
<para>(a quién está dirigido, dónde puede obtenerse, licencia)</para>
</sect1>
</chapter>
<chapter id="settingup">
<title>Configurando su proyecto</title>
<para>Las siguientes secciones describen los pasos que realizar para integrar GTK-Doc en su proyecto. Estas secciones asumen que se trabaja en un proyecto llamado «meep». Este proyecto contiene una biblioteca llamada «libmeep» y una aplicación final de usuario llamada «meeper». También se asume que usará «autoconf» y «automake». En la sección <link linkend="plain_makefiles">Integración con makefiles u otros sistemas de construcción</link> se describen las necesidades básicas para trabajar con un sistema de construcción diferente.</para>
<sect1 id="settingup_docfiles">
<title>Configurar el esquema de la documentación</title>
<para>Bajo su carpeta de nivel superior cree carpetas llamadas docs/reference (de esta forma también puede tener docs/help para la documentación final de usuario). Se recomienda crear otra subcarpeta con el nombre doc-package. Para paquetes con una sola biblioteca este paso no es necesario.</para>
<para>Esto después aparecerá como se muestra debajo: <example><title>Ejemplo de estructura de carpetas</title>
<programlisting>
meep/
docs/
reference/
libmeep/
meeper/
src/
libmeep/
meeper/
</programlisting>
</example></para>
</sect1>
<sect1 id="settingup_autoconf">
<title>Integración con autoconf</title>
<para>Muy fácil, simplemente añada una línea a su script <filename>configure.ac</filename>.</para>
<para>
<example><title>Integración con autoconf</title>
<programlisting>
# check for gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
</programlisting>
</example>
</para>
<para>Esto requerirá que todos los desarrolladores tengan gtk-doc instalado. Si para su proyecto es correcto tener una configuración de construcción de api-doc opcional, puede resolver esto como sigue. Manténgalo como está, ya que gtkdocize busca en <function>GTK_DOC_CHECK</function> al inicio de la línea. <example><title>Mantener gtk-doc como opcional</title>
<programlisting>
# check for gtk-doc
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
</example></para>
<para>El primer argumento se usa para comprobar gtkdocversion durante la configuración. El segundo, y opcional, argumento lo usa <application>gtkdocize</application>. La macro <symbol>GTK_DOC_CHECK</symbol> también añade diversas opciones de configuración:</para>
<orderedlist>
<listitem><para>--with-html-dir=RUTA: ruta a los documentos instalados</para></listitem>
<listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
<listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí]</para></listitem>
<listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
</orderedlist>
<important>
<para>GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción <option>«--enable-gtk-doc»</option> en la siguiente ejecución de <filename>configure</filename>. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores).</para>
</important>
<para>Aún más, se recomienda que tenga la siguiente línea en su script <filename>configure.ac</filename>. Esto permite que <application>gtkdocize</application> copie automáticamente la definición de la macro para <function>GTK_DOC_CHECK</function> a su proyecto.</para>
<para>
<example><title>Preparación para gtkdocize</title>
<programlisting>
AC_CONFIG_MACRO_DIR(m4)
</programlisting>
</example>
</para>
<para>Después de hacer los cambios en el <filename>configure.ac</filename> actualice el archivo <filename>configure</filename>. Esto se puede hacer volviendo a ejecutar <code>autoreconf -i</code> o <code>autogen.sh</code>.</para>
</sect1>
<sect1 id="settingup_automake">
<title>Integración con automake</title>
<para>Primero copie el archivo <filename>Makefile.am</filename> de la subcarpeta <filename class="directory">examples</filename> de <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> a la carpeta de documentación de la API de su proyecto (<filename class="directory">./docs/reference/<package></filename>). Debería haber una copia local disponible en <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Si tiene varios paquetes de documentación, repítalo para cada uno de ellos.</para>
<para>El siguiente paso es editar la configuración dentro de <filename>Makefile.am</filename>. Todos los ajustes tienen un comentario encima que describe su propósito. Muchos ajustes son opciones adicionales pasadas a las respectivas herramientas. Cada herramienta tiene una variable de la forma <option><NOMBRE_DE_LA_HERRAMIENTA>_OPCIONES</option>. Todas las herramientas soportan <option>--help</option> para listar los parámetros que soportan.</para>
<!-- FIXME: explain options ? -->
</sect1>
<sect1 id="settingup_autogen">
<title>Integración con autogen</title>
<para>La mayoría de los proyectos tienen un script <filename>autogen.sh</filename> para configurar la infraestructura de construcción después de hacer un «checkout» desde los sistemas de control de versiones (tales como cvs/svn/git). GTK-Doc tiene una herramienta llamada <filename>gtkdocize</filename> que se puede usar en tal script. Se debería ejecutar antes que autoheader, automake o autoconf.</para>
<para>
<example><title>Ejecutar gtkdocize desde autogen.sh</title>
<programlisting>
gtkdocize || exit 1
</programlisting>
</example>
</para>
<para>Al ejecutar <filename>gtkdocize</filename> copia <filename>gtk-doc.make</filename> a la raíz de su proyecto (o cualquier carpeta especificada por la opción <option>--docdir</option>). También comprueba su script de configuración para la invocación de <function>GTK_DOC_CHECK</function>. Esta macro se puede usar para pasar parámetros adicionales a <application>gtkdocize</application>.</para>
<para>Históricamente GTK-Doc generaba plantillas de archivos donde los desarrolladores introducían los documentos. Al final esto resulto no ser muy bueno (por ejemplo, por la necesidad de tener archivos generados bajo un control de versiones). Desde la versión de DTK-Doc 1.9 las herramientas pueden obtener toda la información desde los comentarios del código fuente y por ello se pueden evitar las plantillas. Se anima a los desarrolladores a mantener su documentación en el código. <application>gtkdocize</application> ahora soporta una opción <option>--flavour no-tmpl</option> que elije un makefile que omite completamente el uso de plantillas. Además de añadir la opción directamente a la línea de comandos al invocarlo, se pueden añadir a una variable de entorno llamada <symbol>GTKDOCIZE_FLAGS</symbol> o configurar como un segundo parámetro en la macro <symbol>GTK_DOC_CHECK</symbol> en el script de configuración. Si nunca ha cambiado un archivo tmpl (plantilla) a mano, elimine la carpeta una vez (ej. desde el sistema de control de versiones).</para>
</sect1>
<sect1 id="settingup_firstrun">
<title>Ejecutar la construcción de la documentación</title>
<para>Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script ejecuta configure automáticamente, entonces debe pasar la opción <option>--enable-gtk-doc</option>. De otra forma, ejecute posteriormente <filename>configure</filename> con esta opción.</para>
<para>El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (.sgml en el pasado), <filename><paquete>-sections.txt</filename>.</para>
<para>
<example><title>Ejecutar la construcción de la documentación</title>
<programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
</example>
</para>
<para>Ahora puede apuntar su navegador a <filename>docs/reference/<paquete>/index.html</filename>. Sí, aún es un poco decepcionante. Pero espere, durante el siguiente capítulo aprenderá a rellenar las páginas con información.</para>
</sect1>
<sect1 id="settingup_vcs">
<title>Integración con los sistemas de control de versiones</title>
<para>Como regla principal, son los archivos que edita los que deberían estar bajo el control de versiones. Para proyectos típicos son los archivos: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (anteriormente .sgml), <filename><paquete>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
<para>Los archivos de las carpetas <filename>xml/</filename> y <filename>html/</filename> No deberían estar bajo control de versiones. Tampoco ninguno de los archivos <filename>.stamp</filename>.</para>
</sect1>
<sect1 id="plain_makefiles">
<title>Integración con makefiles u otros sistemas de construcción</title>
<para>En el caso de que no quiera usar automake y por ello <filename>gtk-doc.mak</filename> deberá llamar a las herramientas gtkdoc en el orden correcto en makefiles propios (o en otras herramientas de construcción).</para>
<para>
<example><title>Pasos de construcción de la documentación</title>
<programlisting>
DOC_MODULE=meep
// sources have changed
gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
// xml files have changed
mkdir html
cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
</programlisting>
</example>
</para>
<para>Deberá mirar en el archivo <filename>Makefile.am</filename> y <filename>gtk-doc.mak</filename> para elegir las opciones adicionales necesarias.</para>
</sect1>
<sect1 id="cmake">
<title>Integración con sistemas de construcción CMake</title>
<para>Ahroa, GTK-Doc proporciona un módulo <filename>GtkDocConfig.cmake</filename> (y el correspondiente módulo <filename>GtkDocConfigVersion.cmake</filename>). Esto proporciona un comando <literal>gtk_doc_add_module</literal> que puede configurar en su archivo <filename>CMakeLists.txt</filename>.</para>
<para>El siguiente ejemplo muestra cómo usar este comando. <example><title>Ejeplo de uso de GTK-Doc desde CMake</title>
<programlisting>
find_package(GtkDoc 1.25 REQUIRED)
# Create the doc-libmeep target.
gtk_doc_add_module(
libmeep ${CMAKE_SOURCE_DIR}/libmeep
XML meep-docs.xml
LIBRARIES libmeep
)
# Build doc-libmeep as part of the default target. Without this, you would
# have to explicitly run something like `make doc-libmeep` to build the docs.
add_custom_target(documentation ALL DEPENDS doc-libmeep)
# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
</example></para>
</sect1>
</chapter>
<chapter id="documenting">
<title>Documentar el código</title>
<para>GTK-Doc usa código fuente comentado con una sintaxis especial para documentar el código. Además obtiene información acerca de la estructura de su proyecto de otras fuentes. En la siguiente sección encontrará información acerca de la sintaxis de los comentarios.</para>
<note>
<title>Ubicación de la documentación</title>
<para>En el pasado la mayoría de la documentación se debía rellenar en campos dentro de la carpeta <filename>tmpl</filename>. Esto tiene las desventajas de que la información. Esto tiene las desventajas de que la información no se actualiza muy a menudo y que el archivo tiene tendencia a causar conflictos con los sistemas de control de versiones.</para>
<para>Para evitar los problemas anteriormente mencionados, se sugiere dejar la documentación dentro de los fuentes. Este manual sólo describe esta forma de documentar el código.</para>
</note>
<para>El analizador puede manejar bien la mayoría de cabeceras de C. En el caso de recibir avisos del analizador que parecen casos especiales, puede sugerir a GTK-Doc que los omita. <example><title>Bloque de comentario de GTK-Doc</title>
<programlisting>
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
</programlisting>
</example></para>
<note>
<title>Limitaciones</title>
<para>Tenga en cuenta que GTK-Doc soporta <code>#ifndef(__GTK_DOC_IGNORE__)</code> pero <code>#if !defined(__GTK_DOC_IGNORE__)</code> u otras combinaciones.</para>
</note>
<!-- -->
<sect1 id="documenting_syntax">
<title>Comentarios de la documentación</title>
<para>Un comentario de varias líneas que comienza con un «*» adicional marca un bloque de documentación que GTK-Doc tools procesarán. <example><title>Bloque de comentario de GTK-Doc</title>
<programlisting>
/**
* identifier:
* documentation ...
*/
</programlisting>
</example></para>
<para>El «identificador» es una línea con el nombre del elemento relacionado con el comentario. La sintaxis difiere un poco dependiendo del elemento. (Por hacer: añadir una tabla mostrando los identificadores)</para>
<para>El bloque de «Documentación» también es diferente para cada tipo de símbolo. Los tipos de símbolos que obtienen parámetros tales como funciones o macros, tienen primero las descripciones seguidas por una línea blanca (exactamente un «*»). Después siguen las descripciones detalladas. Todas las líneas (fuera de los programas; listados y CDATA de la secciones) que solo contengan un « *» (asterisco con espacio) se convierten en párrafos. Si no quiere un espaciado de párrafo, cámbielo a un « * » (espacio-asterisco-espacio). Esto es útil para texto preformateado (listados de código).</para>
<tip>
<para>Al documentar código, describa dos aspectos: <itemizedlist>
<listitem>
<para>Qué es: el nombre de la clase o la función puede confundir a veces a personas que provengan de otros entornos.</para>
</listitem>
<listitem>
<para>Qué hace: indique los usos comunes, en relación con las otras API.</para>
</listitem>
</itemizedlist></para>
</tip>
<para>Una ventaja del hipertexto sobre el texto plano es la capacidad de tener enlaces en el documento. Escribir las marcas adecuadas para un enlace puede ser tedioso aunque GTK-Doc le ayuda proporcionando abreviaturas útiles. <itemizedlist>
<listitem>
<para>Use función() para referirse a funciones o macros que toman argumentos.</para>
</listitem>
<listitem>
<para>Use @parámetro para referirse a parámetros. Úselo también al referirse a parámetros de otras funciones, relacionados al que se describe.</para>
</listitem>
<listitem>
<para>Use %constant para referirse a una constante, ej: %G_TRAVERSE_LEAFS.</para>
</listitem>
<listitem>
<para>Use #símbolo para referirse a otro tipo de símbolos, como por ejemplo estructuras, enumeraciones y macros que no toman argumentos.</para>
</listitem>
<listitem>
<para>Use #Object::signal para referirse a una señal de GObject.</para>
</listitem>
<listitem>
<para>Use #Object:property para referirse a una propiedad de GObject.</para>
</listitem>
<listitem>
<para>Use #Struct.field para referirse a un campo dentro de una estructura y #GObjectClass.foo_bar() para referirse a un vmethod.</para>
</listitem>
</itemizedlist></para>
<tip>
<para>Si necesita usar los caracteres especiales «<», «>», «()», «@», «%», o «#» en su documentación sin que GTK-Doc los cambie, puede usar las entidades XML «&lt;», «&gt;», «amp;lpar;», «amp;rpar;», «amp;commat;» «&percnt;» y «&num;» respectivamente o escaparlas con una contrabarra doble «\».</para>
</tip>
<para>DocBook puede crear algo más que enlaces. También se pueden tener listas, ejemplos, cabeceras e imágenes. En la versión 1.20, la manera prefefira de hacer esto es usando un subconjunto de la sintaxis básica de formateado de texto llamada <ulink url="http://daringfireball.net/projects/markdown/">Marcado</ulink>. En versiones anteriores de GTK-Doc, cualquier documentación que incluya marcado se renderizará como tal. Por ejemplo, los elementos de una lista aparecerán como líneas que empiezan con un guión.</para>
<para>Aunque el marcado es el preferido, puede mezclar ambos. Una limitación aquí es que se puede usar docbook xml con marcado, pero el marcado con docbook xml no está soportado.</para>
<para>En versiones anteriores de GTK-Doc, si necesitaba soporte para formato adicional, necesitaba activar el uso de etiquetas XML dentro de comentarios en la documentación poniendo <option>--xml-mode</option> o <option>--sgml-mode</option> en la variable <symbol>MKDB_OPTIONS</symbol> dentro de <filename>Makefile.am</filename>.</para>
<para>
<example><title>Bloque de comentario de GTK-Doc usando marcado</title>
<programlisting>
/**
* identifier:
*
* documentation paragraph ...
*
* # Sub Heading #
*
* ## Second Sub Heading
*
* # Sub Heading With a Link Anchor # {#heading-two}
*
* more documentation:
*
* - list item 1
*
* Paragraph inside a list item.
*
* - list item 2
*
* 1. numbered list item
*
* 2. another numbered list item
*
* Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
*
* 
*
* [A link to the heading anchor above][heading-two]
*
* A C-language example:
* |[<!-- language="C" -->
* GtkWidget *label = gtk_label_new ("Gorgeous!");
* ]|
*/
</programlisting>
</example>
</para>
<para>Se pueden encontrar más ejemplos de las etiquetas de marcado soportadas en el <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Manual de referencia de sintaxis de marcado de documentación de GTK+</ulink>.</para>
<tip>
<para>Tal y como se ha mencionado antes, la documentación anterior de GTK-Doc es para documentar la API pública .Por ello, no se puede escribir documentación para los símbolos estáticos. No obstante es una buena práctica comentar los símbolos. Esto ayuda a que otros entiendan su código. Por ello se recomienda comentarlos usando comentarios normales (sin el segundo «*» en la primera línea). Si la función, posteriormente, se debe hacer pública, todo lo que el programador debe hacer es añadir otro «*» en el bloque de comentario e introducir el nombre del símbolo en la parte derecha dentro del archivo de secciones.</para>
</tip>
</sect1>
<sect1 id="documenting_sections">
<title>Documentar secciones</title>
<para>Cada sección del documento contiene información acerca de una clase o un módulo. Para introducir el componente puede escribir un bloque de sección. La descripción corta además se usa dentro de la tabla de contenidos. Todos los campos @ son opcionales.</para>
<para>
<example><title>Bloque de comentarios en una sección</title>
<programlisting>
/**
* SECTION:meepapp
* @short_description: the application class
* @title: Meep application
* @section_id:
* @see_also: #MeepSettings
* @stability: Stable
* @include: meep/app.h
* @image: application.png
*
* The application class handles ...
*/
</programlisting>
</example>
</para>
<variablelist>
<varlistentry>
<term>SECCIÓN <nombre></term>
<listitem>
<para>El nombre enlaza la sección de la documentación con la parte respectiva en el archivo <filename><paquete>-sections.txt</filename>. El nombre aquí proporcionado debería coincidir con la etiqueta <ARCHIVO> en el archivo <filename><paquete>-sections.txt</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@short_description</term>
<listitem>
<para>Una línea descrita en la sección, que después aparece tras los enlaces en el TOC y en la página de la sección.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@title</term>
<listitem>
<para>De forma predeterminada el título de la sección es <name> de la declaración SECTION. Se puede sobrescribir con el campo @title.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@section_id</term>
<listitem>
<para>Sobrescribe el uso del título como el identificador de sección. <title> se usa en GObjects como el identificador de sección (section_id) y para otra sección es <MÓDULO>-<title>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@see_also</term>
<listitem>
<para>Una lista de símbolos relacionados con esta sección.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@stability</term>
<listitem>
<para>Esta API tiene una descripción informal del nivel de estabilidad. Se recomienda el uso de uno de estos términos: <itemizedlist>
<listitem>
<para>Estable: La intención de una interfaz estable es la de permitir que terceras partes arbitrarias desarrollen aplicaciones para esas interfaces, las liberen, y confíen que que se podrán ejecutar en todas las publicaciones menores del producto (después de que se introdujese la interfaz en una de ellas, y dentro de la misma versión principal de la publicación). Incluso en publicaciones importantes no se espera que existan cambios incompatibles, y de haberlos habrá buenas razones para ello.</para>
</listitem>
<listitem>
<para>Inestable: Las interfaces inestables son experimentales o de transición. Generalmente se usan para dar a los desarrolladores externos acceso a tecnología nueva o cambiante, o para proporcionar una solución a un problema, anticipándose a una solución más general. No se realizan reclamaciones acerca de la compatibilidad del código o del binario desde una publicación menor a la siguiente.</para>
</listitem>
<listitem>
<para>Privada: Una interfaz que se puede usar en la pila de GNOME en si misma, pero que no está documentada para usuarios finales. Tales funciones sólo se deberían usar de formas especificadas y documentadas.</para>
</listitem>
<listitem>
<para>Interna: Una interfaz que es interna a un módulo y no requiere documentación para el usuario final. Se asume que las funciones que están sin documentar son internas.</para>
</listitem>
</itemizedlist></para>
</listitem>
</varlistentry>
<varlistentry>
<term>@include</term>
<listitem>
<para>Los archivos <literal>#include</literal> para mostrar en la sección del resumen (una lista separada por comas), sobrescribiendo el valor global del <link linkend="metafiles_sections">archivo de secciones</link> o de la línea de comandos. Este elemento es opcional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@image</term>
<listitem>
<para>La imagen para mostrar en la parte superior de la página de referencia, para esta sección. Generalmente será un tipo de diagrama para ilustrar la apariencia visual de una clase o diagrama de su relación con otras clases. Este elemento es opcional.</para>
</listitem>
</varlistentry>
</variablelist>
<tip>
<para>Para evitar recompilaciones innecesarias después de cambios en la documentación ponga los documentos de sección en el código fuente C cuando sea posible.</para>
</tip>
</sect1>
<sect1 id="documenting_symbols">
<title>Documentar símbolos</title>
<para>Cada símbolo (función, macro, estructura, enum, señal y propiedad) está documentado en un bloque separado. La mejor posición para el bloque es junto a la definición del símbolo de tal forma que sea fácil mantenerlos sincronizados. Por ello las funciones generalmente se documentan en el código C y las macros, estructuras y enum en el archivo de cabecera.</para>
<sect2><title>Etiquetas generales</title>
<para>Puede añadir información de versiones a todos los elementos de la documentación para mostrar cuándo se introdujo una API o cuándo se declaró obsoleta.</para>
<variablelist><title>Versionado de etiquetas</title>
<varlistentry><term>Desde:</term>
<listitem>
<para>Descripción desde qué versión del código está disponible la API.</para>
</listitem>
</varlistentry>
<varlistentry><term>Obsoleto:</term>
<listitem>
<para>Párrafo que denota que esta función no se debería usar más. La descripción debería informar al lector de la nueva API.</para>
</listitem>
</varlistentry>
</variablelist>
<para>También puede añadir información de estabilidad a todos los elementos de la documentación para indicar si la se garantiza la estabilidad de la API en todas las versiones menores futuras del proyecto.</para>
<para>El nivel de estabilidad predeterminado para todos los elementos de la documentación se puede establecer pasando el argumento <option>--default-stability</option> a <application>gtkdoc-mkdb</application> con uno de los siguientes valores.</para>
<variablelist><title>Etiquetas de estabilidad</title>
<varlistentry><term>Estabilidad: estable</term>
<listitem>
<para>Marcar el elemento como estable. Esto es para API públicas que está garantizado que serán estables para todas las versiones menores futuras del proyecto.</para>
</listitem>
</varlistentry>
<varlistentry><term>Estabilidad: inestable</term>
<listitem>
<para>Marcar el elemento como inestable. Esto es para las API públicas que se publican como versión previa antes de estabilizarse.</para>
</listitem>
</varlistentry>
<varlistentry><term>Estabilidad: privado</term>
<listitem>
<para>Marcar el elemento como privado. Esto es para interfaces que se pueden usar en módulos fuertemente acoplados, pero no en terceras partes aleatorias.</para>
</listitem>
</varlistentry>
</variablelist>
<example><title>Etiquetas generales</title>
<programlisting>
/**
* foo_get_bar:
* @foo: some foo
*
* Retrieves @foo's bar.
*
* Returns: @foo's bar
*
* Since: 2.6
* Deprecated: 2.12: Use foo_baz_get_bar() instead.
*/
Bar *
foo_get_bar(Foo *foo)
{
...
</programlisting>
</example>
</sect2>
<sect2><title>Anotaciones</title>
<para>Los bloques de documentación pueden contener etiquetas de anotaciones. Estas etiquetas se renderizarán con consejos que describan su significado. Las etiquetas se usan en la introspección de GObject para generar vinculaciones del lenguaje. Puede obtener una lista detallada de las etiquetas soportadas en <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">el wiki</ulink>.</para>
<example><title>Anotaciones</title>
<programlisting>
/**
* foo_get_bar: (annotation)
* @foo: (annotation): some foo
*
* Retrieves @foo's bar.
*
* Returns: (annotation): @foo's bar
*/
...
/**
* foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
* (and another annotation)
* @foo: (annotation) (another annotation): some foo
*
* Sets bar on @foo.
*/
</programlisting>
</example>
</sect2>
<sect2><title>Bloque de comentario de función</title>
<para>Recuerde: <itemizedlist>
<listitem>
<para>El documento, dependiendo de si devuelve objetos, listas, cadenas, etc. debería liberarse/desreferenciarse/etc.</para>
</listitem>
<listitem>
<para>El documento, dependiendo de si sus parámetros pueden ser nulos, y qué sucede si lo son.</para>
</listitem>
<listitem>
<para>Mencionar precondiciones y postcondiciones interesantes donde sea apropiado.</para>
</listitem>
</itemizedlist></para>
<para>GTK-Doc asume que todos los símbolos (macros, funciones) que empiezan por «_» son privados. Se tratan como funciones estáticas.</para>
<example><title>Bloque de comentario de función</title>
<programlisting>
/**
* function_name:
* @par1: description of parameter 1. These can extend over more than
* one line.
* @par2: description of parameter 2
* @...: a %NULL-terminated list of bars
*
* The function description goes here. You can use @par1 to refer to parameters
* so that they are highlighted in the output. You can also use %constant
* for constants, function_name2() for functions and #GtkWidget for links to
* other declarations (which may be documented elsewhere).
*
* Returns: an integer.
*
* Since: 2.2
* Deprecated: 2.18: Use other_function() instead.
*/
</programlisting>
</example>
<variablelist><title>Etiquetas de funciones</title>
<varlistentry><term>Devuelve:</term>
<listitem>
<para>Párrafo que describe el resultado devuelto.</para>
</listitem>
</varlistentry>
<varlistentry><term>@...:</term>
<listitem>
<para>En el caso de que la función tenga argumentos variados debe usar esta etiqueta (@Vargargs: también funciona por razones históricas).</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2><title>Bloque de comentario de propiedad</title>
<example><title>Bloque de comentario de propiedad</title>
<programlisting>
/**
* SomeWidget:some-property:
*
* Here you can document a property.
*/
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
</programlisting>
</example>
</sect2>
<sect2><title>Bloque de comentario de señal</title>
<para>Recuerde: <itemizedlist>
<listitem>
<para>Documentar cuando la señal se emite e indica si se emite antes o después de otras señales.</para>
</listitem>
<listitem>
<para>Documentar qué aplicación debe gestionar las señales.</para>
</listitem>
</itemizedlist></para>
<example><title>Bloque de comentario de señal</title>
<programlisting><![CDATA[
/**
* FooWidget::foobarized:
* @widget: the widget that received the signal
* @foo: some foo
* @bar: some bar
*
* The ::foobarized signal is emitted each time someone tries to foobarize @widget.
*/
foo_signals[FOOBARIZED] =
g_signal_new ("foobarized",
...
]]></programlisting>
</example>
</sect2>
<sect2><title>Bloque de comentario de estructura</title>
<example><title>Bloque de comentario de estructura</title>
<programlisting>
/**
* FooWidget:
* @bar: some #gboolean
*
* This is the best widget, ever.
*/
typedef struct _FooWidget {
GtkWidget parent_instance;
gboolean bar;
} FooWidget;
</programlisting>
</example>
<para>Use <code>/*< private >*/</code> antes de campos de estructuras privadas que quiera ocultar. Use <code>/*< public >*/</code> para revertir el comportamiento anterior.</para>
<para>Si el primer campo es «g_iface», «parent_instance» o «parent_class» se considerará como privado automáticamente y no necesita mencionarse en el bloque de comentario.</para>
<para>También se pueden usar bloques de comentario para GObjects y GObjectClasses. Generalmente es buena idea añadir un bloque de comentario para una clase, si tiene «vmethods» (ya que así se pueden documentar). Para el GObject en si, se puede usar la sección relativa a la documentación, tener un bloque separado para la estructura de la instancia sería útil si la instancia tiene campos públicos. Una desventaja aquí es que esto crea dos entradas de índice con el mismo nombre (la estructura y la sección).</para>
</sect2>
<sect2><title>Enumerar bloques de comentarios</title>
<example><title>Enumerar bloques de comentarios</title>
<programlisting>
/**
* Something:
* @SOMETHING_FOO: something foo
* @SOMETHING_BAR: something bar
*
* Enum values used for the thing, to specify the thing.
*/
typedef enum {
SOMETHING_FOO,
SOMETHING_BAR,
/*< private >*/
SOMETHING_COUNT
} Something;
</programlisting>
</example>
<para>Use <code>/*< private >*/</code> antes de enumerar valores privados que quiera ocultar. Use <code>/*< public >*/</code> para revertir el comportamiento anterior.</para>
</sect2>
</sect1>
<sect1 id="documenting_inline_program">
<title>Documentación en línea del programa</title>
<para>Puede documentar programas y su interfaz de línea de comandos usando la documentación en línea.</para>
<variablelist>
<title>Etiquetas</title>
<varlistentry><term>PROGRAM</term>
<listitem>
<para>Define el inicio de la documentación de un programa.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@short_description:</term>
<listitem>
<para>Define una descripción corta del programa. (Opcional)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@synopsis:</term>
<listitem>
<para>Define el argumento o la lista de argumentos que el programa puede usar. (Opcional)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@see_also:</term>
<listitem>
<para>Página del manual Ver también. (Opcional)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@arg:</term>
<listitem>
<para>Argumentos pasados al programa y su descripción. (Opcional)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Description:</term>
<listitem>
<para>Una descripción más larga del programa.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Devuelve:</term>
<listitem>
<para>Especifique qué valores devuelve el programa. (Opcional)</para>
</listitem>
</varlistentry>
</variablelist>
<sect2>
<title>Ejemplo de documentación de un programa.</title>
<example><title>Bloque de documentación del programa</title>
<programlisting>
/**
* PROGRAM:test-program
* @short_description: A test program
* @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
* @see_also: test(1)
* @--arg1 *arg*: set arg1 to *arg*
* @--arg2 *arg*: set arg2 to *arg*
* @-v, --version: Print the version number
* @-h, --help: Print the help message
*
* Long description of program.
*
* Returns: Zero on success, non-zero on failure
*/
int main(int argc, char *argv[])
{
return 0;
}
</programlisting>
</example>
</sect2>
</sect1>
<sect1 id="documenting_docbook">
<title>Etiquetas DocBook útiles</title>
<para>Aquí están varias etiquetas de DocBook muy útiles al documentar código.</para>
<para>Para enlazar otra sección en GTK docs: <informalexample>
<programlisting>
<link linkend="glib-Hash-Tables">Hash Tables</link>
</programlisting>
</informalexample>. El enlace es el id SGML en el elemento superior de la página a la que quiere enlazar. Para la mayoría de las páginas esta es la parte («gtk», «gdk», «glib») y después el título de página («Tablas hash»). Para los widgets es simplemente el nombre de la clase. Los espacios y guiones bajos se convierten a «-» para ajustarse a SGML/XML.</para>
<para>Para referirse a una función externa, ej. una función de C estándar: <informalexample>
<programlisting>
<function>...</function>
</programlisting>
</informalexample></para>
<para>Para incluir un código de ejemplo: <informalexample>
<programlisting>
<example>
<title>Using a GHashTable.</title>
<programlisting>
...
</programlisting>
</example>
</programlisting>
</informalexample> o posiblemente este, para fragmentos de código muy cortos que no necesitan título: <informalexample>
<programlisting>
<informalexample>
<programlisting>
...
</programlisting>
</informalexample>
</programlisting>
</informalexample>. El último GTK-Doc también soporta abreviación: |[ ... ]|</para>
<para>Para incluir listas de topos: <informalexample>
<programlisting>
<itemizedlist>
<listitem>
<para>
...
</para>
</listitem>
<listitem>
<para>
...
</para>
</listitem>
</itemizedlist>
</programlisting>
</informalexample></para>
<para>Para incluir una nota que sobresale del texto: <informalexample>
<programlisting>
<note>
<para>
Make sure you free the data after use.
</para>
</note>
</programlisting>
</informalexample></para>
<para>Para referirse a un tipo: <informalexample>
<programlisting>
<type>unsigned char</type>
</programlisting>
</informalexample></para>
<para>Para referirse a una estructura externa (no una descrita en la documentación de GTK): <informalexample>
<programlisting>
<structname>XFontStruct</structname>
</programlisting>
</informalexample></para>
<para>Para referirse a un campo o a una estructura: <informalexample>
<programlisting>
<structfield>len</structfield>
</programlisting>
</informalexample></para>
<para>Para referirse a un nombre de clase, se podría usar: <informalexample>
<programlisting>
<classname>GtkWidget</classname>
</programlisting>
</informalexample> pero probablemente estará usando #GtkWidget en su lugar (para crear automáticamente un enlace a la página GtkWidget; consulte <link linkend="documenting_syntax">abreviaciones</link>).</para>
<para>Para enfatizar un texto: <informalexample>
<programlisting>
<emphasis>This is important</emphasis>
</programlisting>
</informalexample></para>
<para>Para uso de nombres de archivo: <informalexample>
<programlisting>
<filename>/home/user/documents</filename>
</programlisting>
</informalexample></para>
<para>Para referirse a claves: <informalexample>
<programlisting>
<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
</programlisting>
</informalexample></para>
</sect1>
</chapter>
<chapter id="metafiles">
<title>Rellenar campos adicionales</title>
<para>Existen tres archivos adicionales que deben mantenerse junto con los comentarios en línea del código fuente: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (.sgml en el pasado) y <filename><paquete>-sections.txt</filename>.</para>
<sect1 id="metafiles_types">
<title>Editar los tipos de archivo</title>
<para>Si su biblioteca o aplicación incluye GObjects puede querer que sus señales, argumentos y/o parámetros y posición en la jerarquía se muestre en la documentación. Todo lo que debe hacer es listar las funciones <function>xxx_get_type</function> junto con sus «include» en el archivo <filename><paquete>.types</filename>.</para>
<para>
<example><title>Fragmento de ejemplo de tipos de archivo</title>
<programlisting>
#include <gtk/gtk.h>
gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type
</programlisting>
</example>
</para>
<para>Desde GTK-Doc 1.8 <application>gtkdoc-scan</application> puede genera esta lista. Simplemente añada «--rebuild-types» a SCAN_OPTIONS en el <filename>Makefile.am</filename>. Si usa esto no debería ejecutar dist sobre los tipos de archivo ni tenerlos bajo el control de versiones.</para>
</sect1>
<sect1 id="metafiles_master">
<title>Editar la sección maestra del documento</title>
<para>GTK-Doc produce documentación en DocBook SGML/XML. Cuando se procesan los comentarios en las líneas del código, las herramientas de GTK-Doc generan una página de documentación por clase o módulo en un archivo aparte. El documento maestro las incluye y ordena.</para>
<para>Puesto que GTK-Doc crea una documento maestro de plantilla, una posterior ejecución no lo modificará de nuevo. Esto significa que se puede estructurar libremente la documentación. Esto incluye agrupar páginas y añadir páginas adicionales. Ahora GTK-Doc tiene un entorno de pruebas, donde también el documento maestro se vuelve a crear desde cero. Es una buena idea mirarlo de vez en cuando para ver si se han introducido algunas mejoras.</para>
<tip>
<para>No crear tutoriales como documentos adicionales. Solamente escriba capítulos adicionales. La ventaja de integrar directamente el tutorial para su biblioteca en la documentación de la API es que es fácil para el tutorial enlazar la documentación de símbolos. Además las posibilidades de actualizar el tutorial junto con la biblioteca son mayores.</para>
</tip>
<para>¿Así que qué es lo que hay que cambiar en el documento maestro? Para empezar es muy poco. Existen algunos «placeholders» (texto entre corchetes) de los que habría que encargarse.</para>
<para>
<example><title>Cabecera del documento maestro</title>
<programlisting>
<bookinfo>
<title>MODULENAME Reference Manual</title>
<releaseinfo>
for MODULENAME [VERSION]
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
<title>[Insert title here]</title>
</programlisting>
</example>
</para>
<para>Se crean además unos pocos elementos de opciones de la manera comentada. Puede revisarlos y activarlos como quiera.</para>
<para>
<example><title>Parte opcional en el documento maestro</title>
<programlisting>
<!-- active esto cuando use anotaciones de introspección de gobject
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-->
</programlisting>
</example>
</para>
<para>Por último, necesita añadir una sección nueva siempre que quiera introducir una. La herramienta <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> le recordará los nuevos archivos xml generados que no estén inclídos todavía en la documentación.</para>
<para>
<example><title>Incluir secciones generadas</title>
<programlisting>
<chapter>
<title>mi biblioteca</title>
<xi:include href="xml/object.xml"/>
...
</programlisting>
</example>
</para>
</sect1>
<sect1 id="metafiles_sections">
<title>Editar el archivo de sección</title>
<para>El archivo de sección se usa para organizar la salida de la documentación por GTK-Doc. Aquí se especifica qué símbolos pertenecen a qué módulo o clase y el control de la visibilidad (pública o privada).</para>
<para>El archivo de sección es un archivo de texto plano con etiquetas que delimitan las secciones. Se ignoran las líneas vacías y las líneas que comiencen con «#» se tratan como comentarios.</para>
<note>
<para>Aunque las etiquetas hacen que el archivo parezca XML, no lo es. No incluya etiquetas del tipo <SUBSECTION>.</para>
</note>
<para>
<example><title>Incluir secciones generadas</title>
<programlisting>
<INCLUDE>libmeep/meep.h</INCLUDE>
<SECTION>
<FILE>meepapp</FILE>
<TITLE>MeepApp</TITLE>
MeepApp
<SUBSECTION Standard>
MEEP_APP
...
MeepAppClass
meep_app_get_type
</SECTION>
</programlisting>
</example>
</para>
<para>La etiqueta <FILE> ... </FILE> se usa para especificar el nombre del archivo, sin sufijo. Por ejemplo, usar «<FILE>gnome-config</FILE>» dará como resultado en la sección de declaraciones la salida <filename>tmpl/gnome-config.sgml</filename> en el archivo de plantilla, que se convertirá al archivo DocBook XML <filename>sgml/gnome-config.sgml</filename> o al archivo DocBook XML <filename>xml/gnome-config.xml</filename>. (El nombre del archivo HTML está basado en el nombre del módulo y en el título de la sección, o para GObjects está basado en el nombre de clase de GObject convertido a minúscula.)</para>
<para>La etiqueta <TITLE> ... </TITLE> se usa para especificar el título de una sección. Sólo es útil antes de que las plantillas (si se usan) se creen inicialmente, ya que el título configurado en la plantilla lo sobrescribe. Además, si una usa comentarios SECTION en los fuentes, se queda obsoleto.</para>
<para>Puede agrupar elementos en la sección usando la etiqueta <SUBSECTION>. Actualmente esto genera una línea en blanco entre subsecciones en la sección de resumen. También puede usar <SUBSECTION Standard> para declaraciones estándar de GObject (ej. funciones como g_object_get_type and macros como G_OBJECT(), G_IS_OBJECT() etc.). Actualmente éstas se han dejado fuera de la documentación. También puede usar <SUBSECTION Private> para declaraciones privadas que no producirán ninguna salida (s una manera práctica de evitar mensajes de advertencia sobre declaraciones sin usar). Si sus bibliotecas contienen tipos privados que no quiere que aparezcan en la jerarquía de objetos o en la lista de interfaces implementados o necesarios, añádalos a una subsección Privada. Si ubica GObject y GObjectClass como estructuras en la sección pública o estándar, depende de si tienen entradas públicas (variables, vmethods).</para>
<para>También puede usar <INCLUDE> ... </INCLUDE> para especificar qué archivos #include se muestran en la sección de resumen. Contiene una lista de archivos #include separados por comas, sin las almohadillas. Si lo configura fuera de cualquier sección, actúa para todas las secciones hasta el final del archivo. Si lo configura dentro de una sección, sólo se aplica a esa sección.</para>
</sect1>
</chapter>
<chapter id="reports">
<title>Controlar el resultado</title>
<para>Una ejecución de GTK-Doc genera archivos de informe dentro de la carpeta de la documentación. Los archivos generados se llaman <filename><paquete>-undocumented.txt</filename>, <filename><paquete>-undeclared.txt</filename> y <filename><paquete>-unused.txt</filename>.Todos son archivos de texto plano y se pueden ver y posprocesar fácilmente.</para>
<para>El archivo <filename><paquete>-undocumented.txt</filename> comienza con el resumen de cobertura de la documentación. Debajo hay dos secciones divididas por líneas vacías. La primera sección lista los símbolos incompletos o indocumentados. La segunda sección hace lo mismo para los documentos de sección. Las entradas incompletas son aquellas que tienen documentación pero dónde; p.e. se ha añadido un parámetro nuevo.</para>
<para>El archivo <filename><paquete>-undeclared.txt</filename> lista símbolos proporcionados en el archivo <filename><paquete>-sections.txt</filename>, pero no encontrados en los fuentes. Compruebe si se han eliminado o no se han escrito correctamente.</para>
<para>El archivo <filename><paquete>-unused.txt</filename> lista nombres de símbolos, donde el analizador de GTK-Doc ha encontrado documentación, pero no sabe dónde ponerla. Esto significa que el símbolo no se ha añadido todavía al archivo <filename><paquete>-sections.txt</filename>.</para>
<tip>
<para>Activar o añadir la línea <option>TESTS=($GTKDOC_CHECK)</option> en Makefile.am. Si como mínimo está instalado GTK-Doc 1.9, esto ejecutará comprobaciones de integridad durante la ejecución de make check.</para>
</tip>
<para>También puede mirar los archivos producidos por el analizador del código fuente: <filename><paquete>-decl-list.txt</filename> y <filename><paquete>-decl.txt</filename>. El primero se puede comparar con el archivo de sección si se mantiene manualmente. El segundo lista todas las declaraciones desde las cabeceras. Si falta un símbolo, se puede comprobar si este archivo lo contiene.</para>
<para>Si el proyecto está basado en GObject, también se puede mirar en los archivos producidos por el analizador de objetos: <filename><paquete>.args.txt</filename>, <filename><paquete>.hierarchy.txt</filename>, <filename><paquete>.interfaces.txt</filename>, <filename><paquete>.prerequisites.txt</filename> y <filename><paquete>.signals.txt</filename>. Si faltan símbolos en cualquiera de ellos, puede hacer que GTK-Doc guarde el análisis de archivos para futuros análisis, pero ejecutándolo como <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
</chapter>
<chapter id="modernizing">
<title>Modernizar la documentación</title>
<para>GTK-Doc ha existido durante mucho tiempo. En esta sección se listan las características nuevas junto con la versión desde la que están disponibles.</para>
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
<para>Al usar XML en lugar de SGML, actualmente se puede nombrar el documento maestro <filename><paquete>-docs.xml</filename>.</para>
<para>Esta versión soporta <option>SCAN_OPTIONS=--rebuild-sections</option> en <filename>Makefile.am</filename>. Cuando está activada, el archivo <filename><paquete>-sections.txt</filename> se genera automáticamente y se puede quitar del control de versiones. Esto sólo funciona en proyectos que tienen una estructura regular (ej. cada pareja .{c,h} creará una sección nueva). Si se organiza un proyecto parecido a esto, actualizar una sección mantenida manualmente puede ser tan sencillo como ejecutar <code>meld <paquete>-decl-list.txt <paquete>-sections.txt</code>.</para>
<para>La versión 1.18 ya introdujo la sintaxis para documentar secciones en las fuentes en lugar de tener que hacerlo en archivos separados bajo <filename class="directory">tmpl</filename>. Esta versión añade opciones para cambiar todo el módulo «doc» del documento para que no realice el paso de construcción de tmpl adicional, usando <option>--flavour no-tmpl</option> en <filename>configure.ac</filename>. Si no tiene una <filename class="directory">tmpl</filename> marcada en su sistema de control de versiones y todavía no ha cambiado, simplemente añada la opción al archivo <filename>configure.ac</filename> y lo tendrá hecho.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
<para>Esta versión soporta <option>SCAN_OPTIONS=--rebuild-types</option> en <filename>Makefile.am</filename>. Cuando está activado, el archivo <filename><package>.types</filename> se genera automáticamente y se puede eliminar del control de versiones. Al usar esta característica es importante configurar la variable <varname>IGNORE_HFILES</varname> en el <filename>Makefile.am</filename> para el código que se construye de manera condicional.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-16">
<title>GTK-Doc 1.16</title>
<para>Esta versión incluye una herramienta nueva llamada gtkdoc-check. Esta herramienta puede ejecutar una serie de comprobaciones de integridad de la documentación. Se activa añadiendo las siguientes líneas al final del archivo <filename>Makefile.am</filename>. <example><title>Activar gtkdoc-check</title>
<programlisting>
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif
</programlisting>
</example></para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-20">
<title>GTK-Doc 1.20</title>
<para>La versión 1.18 incluía soporte para cierto marcado inicial. Usar el marcado en los comentarios del documento es menos intrusivo que escribir el XML del «docbook». Esta versión mejora mucho esto y añade muchos más estilos. La sección que explica la <link linkend="documenting_syntax">sintaxis de los comentarios</link> contiene todos los detalles.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
<para>El makefile distribuído con esta versión genera un archivo de entidad en <filename>xml/gtkdocentities.ent</filename>, que contiene las entidades para, por ejemplo nombre_paquete y versión_paquete. Puede usar este ejemplo en el archivo main.xml para evitar escribir a mano el número de versión. A continuación se muestra un ejemplo que muestra cómo se incluye el archivo de entidad y cómo se usan las entidades. Las entidades también se pueden usar en todos los archivos generados, GTK-Doc usará la misma cabecera XML en los archivos XML generados. <example><title>Usar entidades generadas previamenet</title>
<programlisting>
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>&package_name; Reference Manual</title>
<releaseinfo>
for &package_string;.
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
</releaseinfo>
</bookinfo>
</programlisting>
</example></para>
</sect1>
</chapter>
<chapter id="documenting-others">
<title>Documentar otras interfaces</title>
<para>Hasta ahora se ha usado GTK-Doc para documentar la API del código. Las siguientes secciones contienen sugerencias acerca de cómo se pueden usar las herramientas para documentar otras interfaces.</para>
<sect1 id="commandline-interfaces">
<title>Opciones de la línea de comandos y páginas man</title>
<para>Ya que también se pueden generar páginas man para referencias de entrada docbook, parece buena idea usarlas para ese propósito. De esta forma la interfaz es parte de la referencia y se obtienen las páginas man sin trabajo.</para>
<sect2 id="commandline-interfaces-file">
<title>Documentar la herramienta</title>
<para>Cree un archivo de entrada de referencia para cada herramienta. Siguiendo <link linkend="settingup_docfiles">el ejemplo</link> se llamará <filename>meep/docs/reference/meeper/meep.xml</filename>. Para las etiquetas xml que se deben usar puede mirar al archivo generado en la subcarpeta xml así como los ejemplos en, por ejemplo, glib.</para>
</sect2>
<sect2 id="commandline-interfaces-configure">
<title>Añadir la comprobación de configuración adicional</title>
<para>
<example><title>Comprobaciones de configuración adicionales</title>
<programlisting>
AC_ARG_ENABLE(man,
[AC_HELP_STRING([--enable-man],
[regenerate man pages from Docbook [default=no]])],enable_man=yes,
enable_man=no)
AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
</programlisting>
</example>
</para>
</sect2>
<sect2 id="commandline-interfaces-make">
<title>Añadir reglas de makefile adicionales</title>
<para>
<example><title>Comprobaciones de configuración adicionales</title>
<programlisting>
man_MANS = \
meeper.1
if ENABLE_GTK_DOC
if ENABLE_MAN
%.1 : %.xml
@XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
endif
endif
BUILT_EXTRA_DIST = $(man_MANS)
EXTRA_DIST += meep.xml
</programlisting>
</example>
</para>
</sect2>
</sect1>
<sect1 id="dbus-interfaces">
<title>Interfaces de DBus</title>
<para>(ARREGLAR: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
</sect1>
</chapter>
<chapter id="faq">
<title>Preguntas más frecuentes</title>
<segmentedlist>
<?dbhtml list-presentation="list"?>
<segtitle>Pregunta</segtitle>
<segtitle>Respuesta</segtitle>
<seglistitem>
<seg>Sin jerarquía de clases.</seg>
<seg>Los objetos de la función <function>xxx_get_type()</function> no se han introducido en el archivo <filename><package>.types</filename>.</seg>
</seglistitem>
<seglistitem>
<seg>Aún sin jerarquía de clases.</seg>
<seg>Nombre incorrecto o ausente en el archivo <filename><package>-sections.txt</filename> (consulte la <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explicación</ulink>).</seg>
</seglistitem>
<seglistitem>
<seg>Maldición, aún no hay una jerarquía de clases.</seg>
<seg>Es el nombre del objeto (nombre de la estructura de la instancia, ej. <type>GtkWidget</type>) parte de la sección normal (no ponga esto en Estándar o Privado).</seg>
</seglistitem>
<seglistitem>
<seg>Sin índice de símbolos.</seg>
<seg>¿<filename><package>-docs.{xml,sgml}</filename> contiene un índice que «xi:includes» el índice generado?</seg>
</seglistitem>
<seglistitem>
<seg>Los símbolos no se enlazan con su sección en el documento.</seg>
<seg>¿Está doc-comment usando el marcado correcto (añadido #,% o ())? Compruebe si gtk-doc-fixxref avisa de alguna referencia xref sin resolver.</seg>
</seglistitem>
<seglistitem>
<seg>Una clase nueva no aparece en la documentación.</seg>
<seg>Es la página nueva «xi:included» desde <filename><package>-docs.{xml,sgml}</filename>.</seg>
</seglistitem>
<seglistitem>
<seg>Un símbolo nuevo no aparece en la documentación.</seg>
<seg>Comprobar que el doc-comment está formateado correctamente. Compruebe errores de escritura al principio del comentario. Compruebe si gtkdoc-fixxref avisa acerca de referencias xref no solventables. Compruebe si el símbolo está listado correctamente en <filename><package>-sections.txt</filename> en una subsección pública.</seg>
</seglistitem>
<seglistitem>
<seg>Falta un tipo en la clase de jerarquías</seg>
<seg>Si el tipo está listado en <filename><package>.hierarchy</filename> pero no en <filename>xml/tree_index.sgml</filename>, entonces compruebe dos veces que el tipo está correctamente ubicado en la <filename><package>-sections.txt</filename>. No se mostrará el tipo de instancia (ej. <type>GtkWidget</type>) si no está listada o accidentalmente marcada como privada.</seg>
</seglistitem>
<seglistitem>
<seg>Obtengo enlaces de seguimiento de documentos para todas las anotaciones gobject.</seg>
<seg>Compruebe que <filename>xml/annotation-glossary.xml</filename> está «xi:included» desde <filename><package>-docs.{xml,sgml}</filename>.</seg>
</seglistitem>
<!-- gtk-doc warnings: -->
<seglistitem>
<seg>Parámetro descrito en el bloque de comentarios del código fuente pero no existe</seg>
<seg>Compruebe si el prototipo en la cabecera tiene nombres de parámetro diferentes de la fuente.</seg>
</seglistitem>
<!-- docbook warnings: -->
<seglistitem>
<seg>múltiples «ID» para la restricción enlazada: XYZ</seg>
<seg>El símbolo XYZ aparece dos veces en el archivo <filename><package>-sections.txt</filename>.</seg>
</seglistitem>
<seglistitem>
<seg>Elemento typename en namespace «» encontrado en para, pero ninguna plantilla coincide.</seg>
<seg/>
</seglistitem>
</segmentedlist>
</chapter>
<chapter id="contrib">
<title>Herramientas relacionadas con GTK-Doc</title>
<para>GtkDocPlugin: un complemento de integración <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink> que añade documentos de la API a un sitio «trac» y se integra con la búsqueda de «trac».</para>
<para>Gtkdoc-depscan: una herramienta (parte de gtk-doc) para comprobar la API usada contra etiquetas en la API para determinar la versión mínima necesaria.</para>
</chapter>
<!-- ======== Appendix: FDL ================================== -->
<!--
The GNU Free Documentation License 1.1 in DocBook
Markup by Eric Baudais <baudais@okstate.edu>
Maintained by the GNOME Documentation Project
http://developer.gnome.org/projects/gdp
Version: 1.0.1
Last Modified: Nov 16, 2000
-->
<appendix id="fdl">
<appendixinfo>
<releaseinfo>Versión 1.1, marzo de 2000</releaseinfo>
<copyright><year>2000</year><holder>Free Software Foundation, Inc.</holder></copyright>
<legalnotice id="fdl-legalnotice">
<para><address>Free Software Foundation, Inc. <street>51 Franklin Street,
Suite 330</street>, <city>Boston</city>, <state>MA</state>
<postcode>02110-1301</postcode> <country>USA</country></address>. Se permite la copia y distribución de copias literales de este documento, pero no se permite su modificación.</para>
</legalnotice>
</appendixinfo>
<title>Licencia de documentación libre de GNU</title>
<sect1 id="fdl-preamble">
<title>0. PREÁMBULO</title>
<para>El propósito de esta Licencia es permitir que un manual, libro de texto, u otro documento escrito sea <quote>libre</quote> en el sentido de libertad: asegurar a todo el mundo la libertad efectiva de copiarlo y redistribuirlo, con o sin modificaciones, de manera comercial o no. En segundo término, esta Licencia proporciona al autor y al editor una manera de obtener reconocimiento por su trabajo, sin que se le considere responsable de las modificaciones realizadas por otros.</para>
<para>Esta Licencia es de tipo <quote>copyleft</quote>, lo que significa que los trabajos derivados del documento deben a su vez ser libres en el mismo sentido. Complementa la Licencia Pública General de GNU, que es una licencia tipo copyleft diseñada para el software libre.</para>
<para>Hemos diseñado esta Licencia para usarla en manuales de software libre, ya que el software libre necesita documentación libre: Un programa libre debe venir con los manuales que ofrezcan la mismas libertades que da el software. Pero esta licencia no se limita a manuales de software; puede ser usada para cualquier trabajo textual, sin tener en cuenta su temática o si se publica como libro impreso. Recomendamos esta licencia principalmente para trabajos cuyo fin sea instructivo o de referencia.</para>
</sect1>
<sect1 id="fdl-section1">
<title>1. APLICABILIDAD Y DEFINICIONES</title>
<para id="fdl-document">Esta Licencia se aplica a cualquier manual u otro trabajo que contenga un aviso colocado por el poseedor del copyright diciendo que puede distribuirse bajo los términos de esta Licencia. El <quote>Documento</quote>, abajo, se refiere a cualquier manual o trabajo. Cualquier miembro del público es un licenciatario, y será referido como <quote>Usted</quote>.</para>
<para id="fdl-modified">Una <quote>Versión Modificada</quote> del Documento significa cualquier trabajo que contenga el Documento o una porción del mismo, ya sea una copia literal o con modificaciones y/o traducciones a otro idioma.</para>
<para id="fdl-secondary">Una <quote>Sección Secundaria</quote> es un apéndice con título o una sección preliminar del Documento que trata exclusivamente de la relación entre los autores o editores y el tema general del<link linkend="fdl-document">Documento</link> que trata exclusivamente con la relación entre los editores o autores del Documento con el asunto general del Documento (o asuntos relacionados) y no contiene nada que pueda considerarse dentro del tema principal. (Por ejemplo, si el Documento es en parte un libro de texto de matemáticas, una Sección Secundaria no explicará nada de matemáticas.) La relación puede ser una conexión histórica con el asunto o temas relacionados, o una opinión legal, comercial, filosófica, ética o política acerca de ellos.</para>
<para id="fdl-invariant">Las <quote>Secciones Invariantes</quote> son ciertas <link linkend="fdl-secondary">Secciones Secundarias</link> cuyos títulos son designados como Secciones Invariantes en la nota que indica que el <link linkend="fdl-document">Documento</link> se publica bajo esta Licencia.</para>
<para id="fdl-cover-texts"> Los <quote>Textos de Cubierta</quote> son ciertos pasajes cortos de texto que se listan como Textos de Cubierta Delantera o Textos de Cubierta Trasera en la nota que indica que el <link linkend="fdl-document">Documento</link> se publica bajo esta Licencia.</para>
<para id="fdl-transparent">Una copia <quote>Transparente</quote> del <link linkend="fdl-document">Documento</link>, significa una copia para lectura en máquina, representada en un formato cuya especificación está disponible al público en general, cuyo contenido puede ser visto y editados directamente con editores de texto genéricos o (para imágenes compuestas por píxeles) con programas genéricos de manipulación de imágenes o (para dibujos) con algún editor de dibujos ampliamente disponible, y que sea adecuado como entrada para formateadores de texto o para su traducción automática a formatos adecuados para formateadores de texto. Una copia hecha en un formato definido como Transparente, pero cuyo marcaje o ausencia de él haya sido diseñado para impedir o dificultar modificaciones posteriores por parte de los lectores no es Transparente. Una copia que no es <quote>Transparente</quote> se denomina <quote>Opaca</quote>.</para>
<para>Como ejemplos de formatos adecuados para copias Transparentes están ASCII puro sin marcaje, formato de entrada de Texinfo, formato de entrada de LaTeX, SGML o XML usando una DTD disponible públicamente, y HTML, PostScript o PDF simples, que sigan los estándares y diseños para que los modifiquen personas.Los formatos Opacos incluyen formatos propietarios que pueden ser leídos y editados únicamente en procesadores de textos propietarios, SGML o XML para los cuáles las DTD y/o herramientas de procesamiento no estén ampliamente disponibles, y HTML, PostScript o PDF generados por algunos procesadores de textos sólo como salida.</para>
<para id="fdl-title-page"> La <quote>Portada</quote> significa, en un libro impreso, la página de título, más las páginas siguientes que sean necesarias para mantener legiblemente el material que esta Licencia requiere en la portada. Para trabajos en formatos que no tienen página de portada como tal, <quote>Portada</quote>significa el texto cercano a la aparición más prominente del título del trabajo,precediendo el comienzo del cuerpo del texto.</para>
</sect1>
<sect1 id="fdl-section2">
<title>2. COPIA LITERAL</title>
<para>Usted puede copiar y distribuir el <link linkend="fdl-document">Documento</link> en cualquier soporte, sea en forma comercial o no, siempre y cuando proporcione esta Licencia, las notas de copyright y la nota que indica que esta Licencia se aplica al Documento reproduciéndola en todas las copias y que usted no añada ninguna otra condición a las expuestas en esta Licencia. Usted no puede usar medidas técnicas para obstruir o controlar la lectura o copia posterior de las copias que usted haga o distribuya. Sin embargo, usted puede aceptar compensación a cambio de las copias. Si distribuye un número suficientemente grande de copias también deberá seguir las condiciones de la <link linkend="fdl-section3">sección 3</link>.</para>
<para>Usted también puede prestar copias, bajo las mismas condiciones establecidas anteriormente, y puede exhibir copias públicamente.</para>
</sect1>
<sect1 id="fdl-section3">
<title>3. COPIAR EN CANTIDAD</title>
<para> Si publica copias impresas del <link linkend="fdl-document">Documento</link> que sobrepasen las 100, y la nota de licencia del Documento exige <link linkend="fdl-cover-texts">Textos de Cubierta</link>, debe incluirlas copias con cubiertas que lleven en forma clara y legible todos esos Textos de Cubierta: Textos de Cubierta Delantera en la cubierta delantera y Textos de Cubierta Trasera en la cubierta trasera. Ambas cubiertas deben identificarlo a Usted clara y legiblemente como editor de tales copias. La cubierta debe mostrar el título completo con todas las palabras igualmente prominentes y visibles. Además puede añadir otro material en las cubiertas. Las copias con cambios limitados a las cubiertas, siempre que conserven el título del <link linkend="fdl-document">Documento</link> y satisfagan estas condiciones, pueden considerarse como copias literales en todos los aspectos.</para>
<para> Si los textos requeridos para la cubierta son muy voluminosos para que ajusten legiblemente, debe colocar los primeros (tantos como sea razonable colocar) en la verdadera cubierta y situar el resto en páginas adyacentes.</para>
<para>Si Usted publica o distribuye copias <link linkend="fdl-transparent">Opacas</link> del <link linkend="fdl-document">Documento</link> cuya cantidad exceda las 100, debe incluir una copia <link linkend="fdl-transparent">Transparente</link>, que pueda ser leída por una máquina, con cada copia Opaca, o bien mostrar, en cada copia Opaca, una dirección de red donde cualquier usuario de la misma tenga acceso por medio de protocolos públicos y estandarizados a una copia Transparente del Documento completa, sin material adicional. Si usted hace uso de la última opción, deberá tomar las medidas necesarias, cuando comience la distribución de las copias Opacas en cantidad, para asegurar que esta copia Transparente permanecerá accesible en el sitio establecido por lo menos un año después de la última vez que distribuya una copia Opaca de esa edición al público (directamente o a través de sus agentes o distribuidores).</para>
<para>Se solicita, aunque no es requisito, que se ponga en contacto con los autores del <link linkend="fdl-document">Documento</link> antes de redistribuir gran número de copias, para darles la oportunidad de que le proporcionen una versión actualizada del Documento.</para>
</sect1>
<sect1 id="fdl-section4">
<title>4. MODIFICACIONES</title>
<para>Puede copiar y distribuir una <link linkend="fdl-modified">Versión Modificada</link> del <link linkend="fdl-document">Documento</link> bajo las condiciones de las secciones <link linkend="fdl-section2">2</link> y <link linkend="fdl-section3">3</link> anteriores, siempre que Usted libere la Versión Modificada bajo esta misma Licencia, con la Versión Modificada haciendo el rol del Documento, por lo tanto dando Licencia de distribución y modificación de la Versión Modificada a quienquiera posea una copia de la misma. Además, debe hacer lo siguiente en la Versión Modificada:</para>
<itemizedlist mark="opencircle">
<listitem>
<formalpara>
<title>A</title>
<para>Usar en la <link linkend="fdl-title-page">Portada</link> (y en las cubiertas, si hay alguna) un título distinto al del <link linkend="fdl-document">Documento</link> y de sus versiones anteriores (que deberían, si hay alguna, estar listadas en la sección de Historia del Documento). Puede usar el mismo título de versiones anteriores al original siempre y cuando quien las publicó originalmente otorgue permiso.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>B</title>
<para>Listar en la <link linkend="fdl-title-page">Portada</link>, como autores, una o más personas o entidades responsables de la autoría de las modificaciones de la <link linkend="fdl-modified">Versión Modificada</link>, junto con por lo menos cinco de los autores principales del <link linkend="fdl-document">Documento</link> (todos sus autores principales, si hay menos de cinco), a menos que le eximan de tal requisito.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>C</title>
<para>Mostrar en la <link linkend="fdl-title-page">Portada</link> como editor el nombre del editor de la <link linkend="fdl-modified">Versión Modificada</link></para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>D</title>
<para>Conservar todas las notas de copyright del <link linkend="fdl-document">Documento</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>E</title>
<para>Añadir una nota de copyright apropiada a sus modificaciones, adyacente a las otras notas de copyright.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>F</title>
<para>Incluir, inmediatamente después de los avisos de copyright, una nota de licencia dando el permiso público para usar la <link linkend="fdl-modified">Versión Modificada</link> bajo los términos de esta Licencia, de la forma mostrada en el Adenda de más abajo.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>G</title>
<para>Incluir, inmediatamente después de ese aviso de licencia, la lista completa de <link linkend="fdl-invariant">Secciones invariantes</link> y de los <link linkend="fdl-cover-texts">Textos de Cubierta</link> que sean requeridos en el aviso de Licencia del <link linkend="fdl-document">Documento</link> original.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>H</title>
<para>Incluir una copia sin modificación de esta Licencia.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>I</title>
<para>Conservar la sección titulada <quote>Historia</quote>, conservar su Título y añadirle un elemento que declare al menos el título, el año, los nuevos autores y el editor de la <link linkend="fdl-modified">Versión Modificada</link>, tal como figuran en la <link linkend="fdl-title-page">Portada</link>. Si no hay una sección titulada <quote>Historia</quote> en el <link linkend="fdl-document">Documento</link>, crear una estableciendo el título, el año, los autores y el editor del Documento, tal como figuran en su Portada, añadiendo además un elemento describiendo la Versión Modificada, como se estableció en la sentencia anterior.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>J</title>
<para>Conservar la dirección en red, si la hay, dada en el <link linkend="fdl-document">Documento</link> para el acceso público a una copia <link linkend="fdl-transparent">Transparente</link> del mismo, así como las otras direcciones de red dadas en el Documento para versiones anteriores en las que estuviese basado. Pueden ubicarse en la sección <quote>Historia</quote>. Se puede omitir la ubicación en red de un trabajo que haya sido publicado por lo menos cuatro años antes que el Documento mismo, o si el editor original de dicha versión da permiso.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>K</title>
<para>En cualquier sección titulada <quote>Agradecimientos</quote> o <quote>Dedicatorias</quote>, conservar el título de la sección y conservar en ella toda la sustancia y el tono de los agradecimientos y/o dedicatorias incluidas por cada contribuyente.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>L</title>
<para>Conservar todas las <link linkend="fdl-invariant">Secciones Invariantes</link> del <link linkend="fdl-document">Documento</link>, sin alterar su texto ni sus títulos. Los números de sección o equivalentes no se consideran parte de los títulos de la sección.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>M</title>
<para>Eliminar cualquier sección titulada <quote>Aprobaciones</quote>. Tales secciones no pueden estar incluidas en las <link linkend="fdl-modified">Versiones Modificadas</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>N</title>
<para>No cambiar el título de ninguna sección existente a <quote>Aprobaciones</quote> ni a uno que entre en conflicto con el de alguna <link linkend="fdl-invariant">Sección Invariante</link>.</para>
</formalpara>
</listitem>
</itemizedlist>
<para> Si la <link linkend="fdl-modified">Versión Modificada</link> incluye secciones o apéndices nuevos que cualifiquen como <link linkend="fdl-secondary">Secciones Secundarias</link> y no contienen ningún material copiado del Documento, puede opcionalmente designar algunas o todas esas secciones como invariantes. Para hacerlo, añada sus títulos a la lista de <link linkend="fdl-invariant">Secciones Invariantes</link> en el aviso de licencia de la Versión Modificada. Tales títulos deben ser distintos de cualquier otro título de sección.</para>
<para>Puede añadir una sección titulada <quote>Aprobaciones</quote>, siempre que contenga únicamente aprobaciones de su <link linkend="fdl-modified">Versión Modificada</link> por otras fuentes --por ejemplo, observaciones de compañeros o que el texto ha sido aprobado por una organización como definición oficial de un estándar.</para>
<para>Puede añadir un pasaje de hasta cinco palabras como <link linkend="fdl-cover-texts">Texto de Cubierta Delantera</link> y un pasaje de hasta 25 palabras como <link linkend="fdl-cover-texts">Texto de Cubierta Trasera</link> al final de la lista de <link linkend="fdl-cover-texts">Texto de Cubierta</link> en la <link linkend="fdl-modified">Versión Modificada</link>. Una entidad sólo puede añadir (o hacer que se añada) un pasaje al Texto de Cubierta Delantera y uno al de Cubierta Trasera. Si el <link linkend="fdl-document">Documento</link> ya incluye un textos de cubiertas añadidos previamente por usted o por acuerdo previo con la entidad que usted representa, usted no puede añadir otro; pero puede reemplazar el anterior, con permiso explícito del editor anterior que agregó el texto anterior.</para>
<para>Con esta Licencia ni los autores ni los editores del <link linkend="fdl-document">Documento</link> dan permiso para usar sus nombres para publicidad ni para asegurar o implicar aprobación de cualquier <link linkend="fdl-modified">Versión Modificada</link>.</para>
</sect1>
<sect1 id="fdl-section5">
<title>5. COMBINAR DOCUMENTOS</title>
<para>Usted puede combinar el <link linkend="fdl-document">Documento</link> con otros documentos liberados bajo esta Licencia, bajo los términos definidos en la sección <link linkend="fdl-section4">section 4</link> más arriba para versiones modificadas, siempre que incluya en la combinación todas las <link linkend="fdl-invariant">Secciones Invariantes</link> de todos los documentos originales, sin modificaciones, y las liste todas como Secciones Invariantes de su trabajo combinado en su aviso de licencia.</para>
<para>El trabajo combinado necesita contener solamente una copia de esta Licencia, y múltiples <link linkend="fdl-invariant">Secciones Invariantes</link> idénticas pueden reemplazarse por una sola copia. Si hay múltiples Secciones Invariantes con el mismo nombre pero con contenidos diferentes, haga el título de cada una de estas secciones único añadiéndolo al final de este, entre paréntesis, el nombre del autor o de quien editó originalmente esa sección, si es conocido, o si no, un número único. Haga el mismo ajuste a los títulos de sección en la lista de Secciones Invariantes en la nota de licencia del trabajo combinado.</para>
<para>En la combinación, debe combinar cualquier sección titulada <quote>Historia</quote> de los distintos documentos originales, formando una sección titulada <quote>Historia</quote>; de la misma forma, combine cualquier sección titulada <quote>Reconocimientos</quote> y cualquier sección titulada <quote>Dedicatorias</quote>. Debe eliminar todas las secciones tituladas <quote>Aprobaciones</quote>.</para>
</sect1>
<sect1 id="fdl-section6">
<title>6. COLECCIONES DE DOCUMENTOS</title>
<para>Puede hacer una colección que conste del <link linkend="fdl-document">Documento</link> y de otros documentos publicados bajo esta Licencia, y reemplazar las copias individuales de esta Licencia en todos los documentos por una sola copia que esté incluida en la colección, siempre que siga las reglas de esta Licencia para cada copia literal de cada uno de los documentos en cualquiera de los demás aspectos.</para>
<para>Puede extraer un solo documento de una de tales colecciones y distribuirlo individualmente bajo esta Licencia, siempre que inserte una copia de esta Licencia en el documento extraído, y siga esta Licencia en todos los demás aspectos relativos a la copia literal de dicho documento.</para>
</sect1>
<sect1 id="fdl-section7">
<title>7. AGREGACIÓN CON TRABAJOS INDEPENDIENTES</title>
<para>Una recopilación que conste del <link linkend="fdl-document">Documento</link> o sus derivados y de otros documentos o trabajos separados e independientes, en cualquier soporte de almacenamiento o distribución, no cuenta como un todo como una <link linkend="fdl-modified">Versión Modificada</link> del Documento, siempre que no se reclame ningún derecho de copyright por la compilación. Dicha compilación se denomina un <quote>agregado</quote>, y esta Licencia no se aplica a otros trabajos autocontenidos incluidos con el Documento. teniendo en cuenta que son compilados, si no son los mismos trabajos derivados del Documento. Si el requisito de <link linkend="fdl-cover-texts">Texto de Cubierta</link> de la <link linkend="fdl-section3">sección 3</link> es aplicable a estas copias del Documento, entonces si el Documento es menor que un cuarto del agregado completo, los Textos de Cubierta del Documento pueden colocarse en cubiertas que enmarquen solamente el Documento dentro del agregado. En caso contrario deben aparecer en cubiertas impresas enmarcando todo el agregado.</para>
</sect1>
<sect1 id="fdl-section8">
<title>8. TRADUCCIÓN</title>
<para>La traducción se considera un tipo de modificación, así que puede distribuir traducciones del <link linkend="fdl-document">Documento</link> bajo los términos de la <link linkend="fdl-section4">sección 4</link>. Reemplazar las <link linkend="fdl-invariant">Secciones invariantes</link> con traducciones requiere permiso especial de los mantenedores de la propietarios del copyright, pero puede incluir traducciones de algunos o todas las Secciones invariantes. Puede incluir una traducción de esta licencia proporcionada que además incluya la versión original de esta Sección invariante en adición de esta licencia. En caso de desacuerdo prevalecerá la versión original en inglés.</para>
</sect1>
<sect1 id="fdl-section9">
<title>9. TERMINACIÓN</title>
<para> Usted no puede copiar, modificar, sublicenciar o distribuir el <link linkend="fdl-document">Documento</link> salvo por lo permitido expresamente por esta Licencia. Cualquier otro intento de copia, modificación, sublicenciamiento o distribución del Documento es nulo, y dará por terminados automáticamente sus derechos bajo esa Licencia. Sin embargo, los terceros que hayan recibido copias, o derechos, de usted bajo esta Licencia no verán terminadas sus licencias, siempre que permanezcan en total conformidad con ella.</para>
</sect1>
<sect1 id="fdl-section10">
<title>10. FUTURAS REVISIONES DE ESTA LICENCIA</title>
<para>La <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> puede publicar versiones nuevas y revisadas de la Licencia de Documentación Libre GNU de vez en cuando. Dichas versiones nuevas serán similares en espíritu a la presente versión, pero pueden diferir en detalles para solucionar nuevos problemas o preocupaciones. Vea <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>
<para>Cada versión de la licencia tiene un número de versión. Si la <link linkend="fdl-document">Documentación</link> especifica que el número particular de versión de esta Licencia <quote>o cualquier posterior versión</quote> aplicado sobre él, tiene la opción de seguir los términos y condiciones de cualquiera de esas versiones especificadas o de cualquiera de las versiones publicadas (no como borrador) por la Free Software Foundation. Si el Documento no especifica un número de versión de la licencia, puede elegir cualquier versión publicada (no como borrador) por la Free Software Foundation.</para>
</sect1>
<sect1 id="fdl-using">
<title>Addendum</title>
<para>Para usar esta licencia en un documento que ha escrito, incluya una copia de la Licencia en el documento y ponga el siguiente copyright y las notas justo después del título de la página.</para>
<blockquote>
<para>Copyright 2009-2016 Daniel Mustieles
Copyright 2009-2010 Jorge González González
Copyright 2009-2010 Francisco Javier Fernández Serrador</para>
<para>Se otorga permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia de Documentación Libre de GNU, Versión 1.1 o cualquier otra versión posterior publicada por la Free Software Foundation; con las <link linkend="fdl-invariant">Secciones Invariantes</link> siendo su LISTE SUS TÍTULOS, con <link linkend="fdl-cover-texts">Textos de Cubierta Delantera</link> siendo LISTA, y con los <link linkend="fdl-cover-texts">Textos de Cubierta Trasera</link> siendo LISTA. Una copia de la licencia está incluida en la sección titulada <quote>GNU Free Documentation License</quote>.</para>
</blockquote>
<para>Si no tiene <link linkend="fdl-invariant">Secciones Invariantes</link>, escriba <quote>sin Secciones Invariantes</quote> en vez de decir cuáles son invariantes. Si no tiene <link linkend="fdl-cover-texts">Textos de Cubierta Frontal</link>, escriba <quote>sin Textos de Cubierta Frontal</quote>; de la misma manera para <link linkend="fdl-cover-texts">Textos de Cubierta Trasera</link>.</para>
<para>Si su documento contiene ejemplos de código de programa no triviales, recomendamos liberar estos ejemplos en paralelo bajo la licencia de software libre que usted elija, como la <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">Licencia Pública General de GNU (GNU General Public License)</ulink>, para permitir su uso en software libre.</para>
</sect1>
</appendix>
</book>
|