Cómo trabajar con las páginas web de Debian

Información general

Recursos necesarios

Si va a trabajar en nuestro sitio web, prepárese para almacenar al menos 740 MB de datos en su disco. Esto refleja el tamaño actual del archivo fuente. Si (por accidente) construye todas las páginas, necesitará al menos el triple de espacio.

¿Qué son esas líneas que empiezan por #?

En WML, una línea que empieza por # es un comentario. Se prefieren a los comentarios normales de HTML debido a que los primeros no aparecen en la página final.

Por favor, lea la página sobre el uso de WML para obtener más información acerca de WML.

Etiqueta para los editores

¿Puedo modificar tal página?

Depende. Si ve un pequeño fallo, gramatical, por ejemplo, arréglelo.

Si comprueba que falta algo de información, siéntase libre también de arreglarlo.

Si alguna parte le parece horrible y necesita ser reescrita, coméntelo en debian-www para que podamos discutirlo. Seguramente estaremos de acuerdo con usted.

Si encuentra algún problema en una plantilla (o sea, un fichero en el directorio webwml/english/template/debian), medite el cambio antes de enviarlo, porque los cambios en las plantillas a menudo producen la reconstrucción de grandes partes del sitio web.

Cuando añada nuevos directorios, ¡añada también el Makefile!

Debe prestar atención cuando añada directorios en git. Si el directorio actual está listado en ../Makefile, entonces debe crear un Makefile dentro de él porque, si no, make mostrará un mensaje de error.

Use inglés claro y sencillo

Ya que el web de Debian lo leen personas para las que el inglés no es su idioma nativo y se traduce a varios idiomas, lo mejor es escribir en inglés claro y sencillo y evitar el uso de jerga (slang) y de modismos oscuros.

Si hace algo de esto, ponga un comentario en el fichero explicando su significado.

Si tiene alguna duda, o para poder revisar su propuesta, por favor contacte con el equipo de localización al inglés.

Busque ficheros README

Algunos de los directorios contienen un fichero README para ayudarle a entender cómo se organiza dicho directorio. Estos deberían proporcionar toda la información necesaria cuando se trabaja en esa área.

Separe los cambios en el contenido de los cambios en el formato

Haga siempre parches o commits separados para los cambios en el contenido y los cambios en el formato. Cuando se combinan, es más difícil para los traductores encontrar las diferencias. Si ejecuta git diff -u con tales cambios, podrá ver el desastre usted mismo.

En general, evite cambios aleatorios en el formato. No debería hacer compatibles con XHTML/XML partes viejas de una página en el mismo commit con otros cambios. (Las cosas nuevas pueden y deben hacerse adecuadamente desde el principio, claro está).

Actualice las traducciones también, si fuera posible

Algunos cambios son idependientes del idioma usado en el fichero WML, como cambios en una URL o en código Perl embebido. La corrección de fallos al escribir también cae en esta misma categoría, puesto que los traductores suelen ignorarlos al traducir. Con este tipo de cambios independientes del idioma, puede hacer el mismo cambio en todos los ficheros traducidos sin saber en realidad otros idiomas, y modificar sin problemas la versión de la cabecera translation-check.

No es que sea terriblemente duro para los traductores hacer el trabajo ellos mismos, y puede ser inconveniente para editores anglo-parlantes tener una descarga completa sobre la que trabajar. Sin embargo, animamos a la gente a que lo haga para evitar molestar a dos docenas de personas por algo que podría hacer rápidamente una.

Además, para hacer más fácil aplicar estos cambios, puede usar el script smart_change.pl desde el directorio raíz del módulo git webwml.

Enlaces

«Este enlace no parece correcto. ¿Debería cambiarlo?»

Debido a la manera en que están configurados los servidores web (utilizando negociación de contenido), no tendría por qué cambiar ninguno de los enlaces internos. En realidad, le sugerimos que no lo haga. Escriba a debian-www si piensa que un enlace es incorrecto antes de cambiarlo.

Correción de enlaces

Si observa un enlace a un sitio web externo que resulta en una redirección (301, 302, una redirección <meta>, o una página que diga Esta página ha cambiado de sitio.), indíquelo por favor en debian-www.

Si encuentra un enlace roto (404, 403, o una página que no es lo que el enlace dice), por favor, corríjalo e indíquelo en debian-www de manera que los traductores se enteren. Incluso mejor aún, corrija el enlace en todas las traducciones, y actualice las cabeceras translation-check si es posible.

Separación de texto y datos

¿Qué son esos ficheros algo.def y algo.data?

Para facilitar que las traducciones estén al día, separamos las partes genéricas (datos) de las partes textuales (texto) en algunas páginas. Los traductores solo necesitan copiar y traducir las partes textuales, las partes genéricas serán añadidas automáticamente.

Un ejemplo le ayudará a entenderlo. Se necesitan varios ficheros para generar la página de vendedores:

index.wml:
El texto en la parte superior de la página de vendedores está en este fichero. Se debería colocar una copia en el directorio de la traducción.
vendors.CD.def:
Este contiene todas las secciones de texto que se necesitan para cada vendedor. Las traducciones deberían ser añadidas mediante <language>/po/vendors.xy.po.
vendors.CD:
Este fichero contiene los datos reales de los vendedores que son independientes del idioma, de manera que un traductor no necesita tocar este fichero.

Cuando una de las personas detrás de cdvendors@debian.org añade un nuevo vendedor, lo hace a debiancd.db, lo convierte en código WML como vendors.CD (usando getvendors.pl), y deja que WML y los ficheros "makefile" hagan su magia. Todas las traducciones son reconstruidas usando el texto ya traducido, pero con los datos del nuevo vendedor. ¡Una traducción actualizada gratis!

Añadir nuevas páginas

Añadir nuevas páginas a Debian es bastante fácil. Todo el trabajo para hacer correctamente la cabecera y pie de página se hace con WML. Todo lo que usted necesita hacer es incluir una línea como la siguiente al principio de cada fichero nuevo:

#use wml::debian::template title="TÍTULO DE LA PÁGINA"

seguida del cuerpo. Todas las páginas usan la plantilla wml::debian::template a no ser que usen una especial creada solamente para esa sección, por ejemplo, los apartados de noticias o seguridad.

Las plantillas que tenemos le permiten definir ciertas variables que afectarán a las páginas creadas. Esto debería evitar el tener que crear diferentes plantillas para cada situación y permitir que las mejoras sean más sencillas de implementar. Las variables que actualmente están disponibles junto con su propósito son:

BARETITLE="true"
Borra la parte "Debian --" que usualmente se encuentra antes de todas las marcas <title>.
NOHEADER="true"
Borrar la cabecera inicial de la página. Por supuesto, puede incluirse una cabecera personalizada en el cuerpo.
NOMIRRORS="true"
Elimina la lista de servidores espejo de la página. No se recomienda su uso, excepto para un puñado de páginas.
NOHOMELINK="true"
Borra el enlace de vuelta a la página principal de Debian, que normalmente se añade al final de la página.
NOLANGUAGES="true"
Borra los enlaces de las versiones en otros idiomas que normalmente se añade al final de la página.
GEN_TIME="true"
Configura la fecha de los ficheros resultantes con la marca de tiempo de los ficheros generados, en vez de la marca de tiempo del fichero fuente.
NOCOPYRIGHT="true"
Borra la nota de copyright del final de la página.

Tenga en cuenta que puede usar cualquier cadena de caracteres como el valor de estas variables, true, yes, foo, da igual.

Un ejemplo de su uso se encuentra en las páginas de las migraciones (ports), que tienen sus propias cabeceras. ports/arm/index.wml usa:

#use wml::debian::template title="ARM Port" NOHEADER="yes"

Si usted desea hacer algo que no puede hacer usando las plantillas existentes, considere primero extender alguna de ellas. Si no es posible extender una de ellas de una forma compatible con las versiones anteriores, intente hacer que la plantilla existente sea un subconjunto de la nueva plantilla, de forma que las páginas puedan convertirse a esta en la siguiente actualización principal (esperemos que nunca más de 6 meses).

Si usted crea una página que es generada por un script o tiene poco texto, considere el uso de etiquteas <gettext> para facilitar la tarea de mantener las traducciones al día.

Incluir otros archivos

Si quiere separar algunas partes de su página en un archivo distinto (que después es incluido por su archivo principal), utilice la extensión .src si su archivo tiene contenido que se debería traducir porque, así, al archivo incluido se le hace un seguimiento de los cambios como a cualquier archivo .wml ordinario. Si usa cualquier otra extensión, como .inc, los traductores no tendrán noticias de sus actualizaciones y las diferentes lenguas pueden mostrar contenidos diferentes.

Añadir un nuevo directorio

Nota: no cree un directorio con el nombre install. Esto confunde a make y las páginas en ese directorio no se actualizarán automáticamente.

Seguidamente se encuentra un ejemplo comentado de cómo añadir un nuevo directorio foo al servidor web.

   mkdir foo
   git add foo
   cd foo
   cp ../intro/Makefile .
   git add Makefile

Edite el fichero Makefile en el directorio padre y añada el directorio que acaba de crear en la variable SUBS. Esto añadirá el directorio a la construcción cuando ejecute make.

Finalmente, envíe todos los cambios recién hechos al repositorio con 

  git commit Makefile foo