Manual Para AROS

Manual para la Documentación de AROS

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.

Contenido

• Introducción

• Escribir la documentación

o El archivo de la documentación

o Los subdirectorios

o La internacionalización

o El código de muestra

o Las imágenes

o Envío

• Notas técnicas

o Las bases de datos

 credits

 quotes

 mirrors

 tasks

 Sizes

o Building

 Requerimientos

 Setting up

 Targets

 Procedimiento

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:

• Quick reStructuredText Reference

El archivo de la documentación

Para cambiar o escribir la documentación necesitas descargar del subversion archive 'documentation'. El archivo contiene:

• algunos documentos comunes como contact.en, links.en, etc.

• un directorio 'documentation' con la documentación del usuario y del desarrollador

• un directorio 'scripts' con los guiones usados para compilar los targets HTML y WWW

• ...

Nota

El archivo de subversion y el directorio con los manuales del usuario y del desarrollador tienen el nombre 'documentation'. No los mezcles.

Los subdirectorios

Puedes 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ón

El 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 muestra

El directorio 'documentation/developers/samplecode' está para los ejemplos en código fuente. El contenido se copia sin modificar a los targets.

Las imágenes

Los 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ío

Antes 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://www.aros.org algunas horas después de su envío.

Notas técnicas

Las bases de datos

Hay 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.

credits

Esto 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.

quotes

Las citas notables de las celebridades de AROS. El formato es dicho;autor. El build system copia este archivo al target HTML.

mirrors

Puesto que AROS está alojado en Sourceforge no hay servidores espejo. Este archivo es ignorado por el build system.

tasks

Es la base de datos TODO (Para Hacer). Este archivo no ha sido mantenido por un largo tiempo y no es usado para los targets.

Sizes

Los archivos aros.size y contrib.size no se usan más y es probable que serán borrados.

Building

Requerimientos

Necesitarás lo siguiente para compilar la documentación de AROS desde cero:

• Python 2.2.1

Para construir el sitio web necesitarás adicionalmente:

• The Python Imaging Library 1.1.3

MacOS X viene con Python pre-instalado, pero para compilar el sitio web necesitarás:

• The Darwinports package

• The Darwinports Python Imaging Library 1.1.3

Setting up

Antes 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.

Targets

En este momento hay dos targets soportados:

• www

Este target genera el sitio web de AROS que incluye toda la documentación, las novedades-noticias, las galerías de fotografías con miniaturas y la información del estado. La documentación se integrará

...