Manual para la Documentación de AROSAdvertencia ¡Este documento no está terminado! Es muy probable que muchas partes estén anticuadas, contengan información incorrecta o simplemente falten. Si quieres ayudar a rectificar esto, por favor contáctanos. Este manual describe el sistema de documentación de AROS. Está dirigido a los escritores de la documentación como también a los desarrolladores que deseen extender o enredarse con el sistema en sí. Con este fin, el manual está separado en tres partes: una introducción común, el modo de escribir la documentación y por último las notas técnicas y las especificaciones. Además de informar sobre el uso del sistema, el segundo capítulo también contiene algunas directrices generales a seguir cuando se escriba la documentación de AROS. IntroducciónLa documentación es vital para cualquier proyecto, al hacerlo útil. Lo usual, en un proyecto con tan limitados esfuerzos de desarrollador como el nuestro, es que la documentación esté considerablemente demorada o ausente. Además, la mayoría de los programadores no son tan buenos escribiendo documentos, así que lo que ya se escribió en general no es legible. Se necesitan combinar los esfuerzos de los desarrolladores y de los usuarios para que la documentación llegue a la meta de un "AROS Ultimate Documentary". Así que si sabes de algunos usuarios que puedan ayudarnos, ¡sólo permíteles! =) FIXME: ¿Escribir algo más? Escribir la documentaciónEl formato de la documentación que usamos es ReStructuredText (o para abreviar ReST) como está especificado en el Docutils Project. ReST es una sintaxis de marcas de texto plano, extensible, fácil de leer y de escribir y del tipo "obtienes lo que ves". Puede describirse como un híbrido entre una sintaxis de marcas implícita y una de marcas explícita, que lo hace fácil de aprender y muy legible, y a la vez poderoso y extensible. La Introduction to reStructuredText contiene algunos buenos puntos sobre las metas que tiene la sintaxis. Dado que el formato es básicamente texto plano es muy fácil de aprender simplemente inspeccionando la documentación existente y usando el sentido común, no obstante se recomienda al menos una ligera lectura del ReStructuredText Primer antes de empezar a trabajar en la documentación de AROS. Para más información sobre el formato, se recomienda leer los siguientes documentos: El archivo de la documentaciónPara cambiar o escribir la documentación necesitas descargar del subversion archive 'documentation'. El archivo contiene:
Nota El archivo de subversion y el directorio con los manuales del usuario y del desarrollador tienen el nombre 'documentation'. No los mezcles. Los subdirectoriosPuedes crear directorios adicionales en 'documentation/users' y en 'documentation/developers'. El build system explora recursivamente los subdirectorios. Se recomienda que crees un archivo 'index.en' en los nuevos directorios. La internacionalizaciónEl build system soporta I18n para el target 'www'. Tienes que agregar un sufijo de idioma al nombre del archivo del documento (por ej. commands.en). Actualmente hay soporte para el inglés (.en), alemán (.de), finés (.fi), italiano (.it), ruso (.ru), sueco (.sv) y holandés (.nl). Si deseas traducir la documentación a más idiomas entonces por favor ponte en contacto con nosotros a través de la website mailing list. Cuando creas un enlace a un documento tienes que omitir el sufijo (por ej. `Commands <user/commands>`_). Pero si usas el directorio 'include' para los documentos traducidos debes dejar el sufijo. El build system usa la versión en inglés cuando no está disponible la traducción de una página. El código de muestraEl directorio 'documentation/developers/samplecode' está para los ejemplos en código fuente. El contenido se copia sin modificar a los targets. Las imágenesLos nombres y las rutas de las imágenes están hard-coded en el guión de python 'buildit.py'. Si quieres agregar imágenes tienes que cambiar el guión. Siéntete en libertad de hacer un pedido de característica en la lista de correo del desarrollador si quieres que esto se cambie. EnvíoAntes que envíes los documentos nuevos o modificados deberías build ambos targets HTML y WWW localmente. Busca los mensajes de error y repáralos. Comprueba el resultado en un navegador web. Lo normal es que los cambios sean aplicados a http://aros.sourceforge.net/ algunas horas después de su envío. Notas técnicasLas bases de datosHay varias pequeñas bases de datos, que puedes encontrar en el directorio db, que están en texto plano pero usan un par de formatos ligeramente diferentes. Principalmente, esto es un artefacto histórico y quizás debería ser rectificado en el futuro, pero por ahora es más fácil mantenerlos tal como están. creditsEsto es una lista de las personas que han contribuído con AROS. El build system crea el archivo 'credits.en'. Este archivo se usa en ambos targets WWW y HTML. Por favor fíjate que también deberías cambiar el archivo workbench/system/AboutAROS/db/credits en el depósito de AROS. quotesLas citas notables de las celebridades de AROS. El formato es dicho;autor. El build system copia este archivo al target HTML. mirrorsPuesto que AROS está alojado en Sourceforge no hay servidores espejo. Este archivo es ignorado por el build system. tasksEs la base de datos TODO (Para Hacer). Este archivo no ha sido mantenido por un largo tiempo y no es usado para los targets. SizesLos archivos aros.size y contrib.size no se usan más y es probable que serán borrados. BuildingRequerimientosNecesitarás lo siguiente para compilar la documentación de AROS desde cero:
Para construir el sitio web necesitarás adicionalmente:
MacOS X viene con Python pre-instalado, pero para compilar el sitio web necesitarás:
Setting upAntes de que empieces a compilar la documentación, podría ser necesario algún ajuste si la versión necesaria del interpretador Python no se llama "python" en tu sistema. Si no es así, simplemente puedes saltar esta sección. Primero, copia los ajustes por omisión: % cd AROS/documentation/scripts/config % cp defaults user Después, edita el archivo user y asegúrate que las variables son correctas para tu sistema. Un archivo de configuración de ejemplo podría verse algo así: PYTHON=python PYTHON indica el nombre del interpretador de Python; podría también ser una ruta absoluta si no lo tienes en la ruta de búsqueda. Podrías necesitar establecerlo a python2 o python2.2 en algunos sistemas. TargetsEn este momento hay dos targets soportados:
ProcedimientoPara compilar un target específico, simplemente invoca el guión de compilación con el nombre del target como primer argumento. El directorio actual necesita ser la raíz del árbol de la documentación. Por ejemplo, para compilar el sitio web haz: > cd AROS/documentation > ./build www Si quieres compilar la documentación HTML separada: > cd AROS/documentation > ./build html Consejo: agregar un sufijo de idioma (por ej. en, du o it) después del nombre del target dará solamente las páginas para ese lenguaje. Todas las páginas faltantes o no traducidas serán substituídas por sus contrapartes en inglés. Esto resulta en tiempos de compilación enormemente reducidos. > cd AROS/documentation > ./build www du Los archivos generados serán puesto en ../bin/documentation/<target-name>, por ej. ../bin/documentation/www para el target www. Los archivos específicos de un lenguajes son puesto en ../bin/documentation/<target-name>/<language-name>. Adicionalmente, hay un target clean, que borrará entero el directorio ../bin/documentation. Nota Actualmente hay muchos archivos intermedios generados en los directorios fuente, así que no puedes ponerlos en un sistema de archivo de solo-lectura. Si haz descargado los fuentes desde SVN no necesitas preocuparte: los archivos generados son ignorados según sea apropiado. |
Copyright © 1995-2024, The AROS Development Team. All rights reserved.
Amiga® is a trademark of Amiga Inc. All other trademarks belong to their respective owners. |