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 250 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 doble de espacio. Si sólo ha hecho una descarga parcial, será mucho menos (por ejemplo, 50 MB para english/).

Descargas parciales

Mucha gente no descarga la totalidad del árbol CVS webwml, lo que a veces conduce a tener ficheros perdidos o a pruebas fallidas, en caso de que se haya añadido un fichero crucial y no se haya hecho un cvs update completo en el directorio. Recuerde comprobar que tenga todos los ficheros necesarios (como los .wmlrc) antes de quejarse.

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

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 al CVS. Si el directorio actual está listado en ../Makefile, entonces debe crear un Makefile dentro suyo — 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 palabras de idiomas extraños e inglés antiguo.

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

Busque ficheros README

Algunos de los directorios contienen un fichero README para ayudarle a entender cómo se organiza dicho directorio. Éstos deberían proporcionar toda la información necesaria cuando se trabaja en ese á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 cvs diff 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-parlates tener que hacer un checkout completo sobre el 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 del directorio superior en el módulo webwml de CVS.

Uso de smart_change.pl

smart_change.pl [opciones] ficheroorigen

Actualmente sólo se permiten ficheros bajo /english/ como ficheroorigen. smart_change.pl admite los siguientes argumentos:

-s, --substitute=REGEXP
Especifica una expresión regular en perl que se aplica a los ficheros fuente (puede usarse más de una vez). Ejemplo: 
         $> ./smart_change.pl -s "s,http://urlvieja/,http://urlnueva/,g" english/devel/index.wml
	 $> cvs diff -u */devel/index.wml | less
	 $> cvs ci -m "1.23: urlvieja colocada en la ubicación actual" */devel/index.wml
La primera orden hace el cambio; el segundo, simplemente checa el archivo original en Inglés y toda traducción de él. Debe hacer ésto para revisar los cambios actuales antes de enviar (commit). Si todo luce como ud. espera, envíe los cambios con el tercer comando.
-l, --lang=CADENA
Procesa este idioma (puede usarse más de una vez). Si no se especifica el idioma, se procesan todos los disponibles.
-n, --no-bump
No incrementa las versiones en las cabeceras translation-check. Normalmente, la versión de cada cabecera translation-check se incrementa en uno en el fichero traducido que están al día, y se deja sin tocar en aquellos que están obsoletos. Si se especifica esta opción, no se toca ninguna cabecera translation-check. Vea Cómo mantener las traducciones al día si desea una explicación sobre las cabeceras translation-check.
-p, --previous
Muestra la revisión de CVS anterior. Esto es útil principalmente cuando el fichero en inglés ya ha sido enviado y quiere comprobar las cabeceras translation-check frente a la versión anterior.
-h, --help
Muestra una información breve sobre uso.
-v, --verbose
Muestra mensajes prolijos mientras funciona.

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), de algunas páginas. Los traductores sólo necesitan copiar y traducir las partes textuales; ya que 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" hagna 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"

seguido 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. Ésto 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 GNU/Linux --" 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 ésta 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 entonces se incluya en su archivo principal), utilice la extensión .src si su archivo contiene contenido que se debería traducir porque entonces a su archivo incluido se le hace un seguimiento de los cambios como cualquier archivo .wml ordinario. Si su 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. Ésto 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
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

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

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

  cvs commit Makefile foo