El rediseño de gentoo.org, Parte 4: El renacimiento de un sitio

1.  El toque final

Un nuevo aspecto, pero...

Al final de artículo anterior, el sitio Web Gentoo Linux tenía un nuevo aspecto completamente diferente, pero todavía hay cosas que no están completas aún. En este artículo, la última entrega de la serie, doy los toques finales al sitio, resultando un sitio basado en XML, refinado, completamente operativo y modular que está preparado para el futuro. A continuación se muestra lo que faltaba en es sitio desde el último artículo.

Finales flojos

En primer lugar, a pesar de que el sitio tenía un aspecto completamente nuevo, solo la parte de la documentación del sitio estaba basada en XML. La páginas principales de las "categorías" están aún en HTML puro y necesitan ser convertidas a una solución XML para hacer las cosas más mantenibles y expandibles.

También, mis desarrolladores han encontrado varios problemas con el HTML puro en sí mismo. El sitio tiene mal aspecto cuando se mira con Netscape 4.77 -- obviamente, esto es un problema. También, hay algunos otros pequeños problemas con la renderización, que aparecen en navegadores modernos, el más molesto de todos es el de una línea negra vertical que no se extiende completamente a lo largo de toda la página, arruinando la ilusión de que el área de contenido principal es dicha por el platillo volante. También, nuestras páginas de documentación no se adaptan al aspecto más refinado de las páginas principales de categorías -- claramente algo merece ser actualizado.

El objetivo

Este es el plan para los trabajos finales en el sitio Gentoo Linux. Primero, reharemos totalmente la página principal HTML, guardando el mismo aspecto global, pero haciendo la página más compatible con los navegadores. Al mismo tiempo, añadiremos algunos refinamientos relacionados con la presentación, sugeridos por nuestros invitados y también corregiremos problemas de compatibilidad con los navegadores en nuestro sistema actual de documentación "guía".

A continuación, moveremos completamente el sitio a XML y XSLT. Al final de este artículo, cualquier cambio en el sitio será realizado modificando XML o XSLT en lugar de editar HTML directamente, el cual será ahora generado automáticamente con la ayuda de xsltproc. Esto hará que todo el sitio sea bastante más fácil de mantener. Ya que Gentoo Linux es un proyecto desarrollado por la comunidad, esto permitirá a nuestros desarrolladores (y a mí) mantener y mejorar el sitio de la forma que sea necesaria. Estoy realmente ilusionado con todo esto, ya que nos ahorrará un montón de tiempo y asegurará que nuestros invitados sean bienvenidos con contenido actualizado.

Aspectos de compatibilidad

Aunque Netscape 4.x es todavía un navegador usado ampliamente, es difícil para mí decidir exactamente cuantos aros hay que saltar para hacer que el sitio tenga mejor aspecto cuando se mire con este navegador. ¿Debo simplemente asegurarme que el sitio es legible? (sin ningún fallo importante) o ¿Debo hacer todo lo que pueda para asegurarme de que el sitio se ve absolutamente perfecto con Netscape 4.x incluso si eso supone usar menos o ningún CSS y añadir ajustes extraños de compatibilidad al HTML existente?.

Al final decidí hacer varios cambios importantes al HTML de modo que el sitio se viera bien con Netscape 4.x sin enfocar demasiado en errores menores relacionados con es espaciado en las tablas o el renderizado de fuentes. A continuación se muestran algunos de los cambios al HTML del sitio para hacerlo del todo compatible con 4.x. (El equipo de desarrollo de Gentoo Linux ha enviado algunas de estas correcciones).

En primer lugar Netscape 4.x tiene un error que hace que los colores de fondo de los bloques de elementos CSS sean mostrados incorrectamente. Por ejemplo, aquí se muestra como una parte en particular de un documento guía debe ser renderizada:

Ilustración 1.1: Un simple documento guía en IE5

Y ahora, cómo Netscape 4.x renderiza esta misma porción cuando los colores de fondo son especificados usando CSS:

Ilustración 1.2: Un simple documento guía en Netscape 4.7; se necesitan algunas correciones

Esto queda feo. Para solucionarlo, los elementos de nivel de bloque como este...

<p class="note">Este párrafo no tiene buen aspecto en 4.x</p>

...fue reemplazado con tablas, de esta forma:

<table width="100%" border="0" cellpadding="0" cellspacing="0">
        <tr>
                <td bgcolor="#ddffff"><p class="note">
                Esto tiene bastante mejor aspecto en 4.x</p></td>
        </tr>
</table>

Este arreglo corrige el problema del renderizado del fondo. Sin embargo, Esta "corrección" también requiere que la información de color sea incluida en el HTML, el cual, en primer lugar, mina los beneficios de usar CSS. Esta es una situación desafortunada, especialmente para los fans de CSS como yo, pero se necesita para la compatibilidad con Netscape 4.x.

Reconstruyendo el HTML

Ahora es el momento de tratar con la línea negra vertical que no siempre se extiende hasta el final de la pantalla. He sido incapaz de encontrar una solución a este problema que funcione tanto en navegadores 4.x como 5.x; cada versión 5.x ha desatado errores en Netscape 4.x, y cada versión compatible 4.x se ve horrible en un navegador 5.x. Por ello, decidí simplemente quitar la linea negra completamente; Finalmente, el sitio funciona en la mayoría de navegadores populares. A continuación crearé una sintaxis parecida a las guías para crear las páginas principales.

Acercándonos a XML

En lugar de implementar un conjunto de etiquetas completamente nuevo para la página principal, creo que sería una buena idea intentar usar la mayor cantidad posible de las etiquetas de documentación "guía" XML (mire la parte 2 de esta serie para más información del formato guía XML). Por ello jugué un poco con nuevos XSL, usando mi formato guía XSL como plantilla para mi trabajo. Después de una hora o dos, tenía un conjunto completamente funcional de transformaciones XSL para convertir una sintaxis del tipo guía en una página principal HTML. La revisión 2 de la nueva página principal tiene este aspecto:

Ilustración 1.3: La nueva revisión de la página principal

Ahora que la página principal está usando un nuevo soporte XML/XSLT, dirigí mi atención a la salida HTML del sistema "guía". No solo necesité corregir un montón de errores de compatibilidad con Netscape 4.7, sino que también necesité actualizar los gráficos y el HTML generado de forma que se adapten a la nueva página principal revisada. Entonces la idea me llegó: ¿Por qué no simplemente ajusto mi nueva página principal XML/XSL un poquito de forma que pueda también generar HTML para mi documentación?. Después de todo, simplemente he añadido soporte para casi todas las etiquetas "guía" XML, para que también puedan ser usadas para el contenido de la página principal.

Esta solución llegó a ser realmente fácil de implementar. Simplemente ajusté el fichero XSLT para que quitara la "barra de enlaces" de la parte izquierda y realicé algunos otro pequeños cambios a la salida del HTML cuando se procesan las páginas de documentación. Ya que la mayor parte del XSLT sigue siendo el mismo, puedo usar un conjunto maestro único de plantillas tanto para la guía de documentación como para las páginas de categorías:

Ilustración 1.4: Cómo trabaja el nuevo XSL

No solo tengo ahora un único conjunto de plantillas XSLT que mantener, sino que ahora comparten la misma hoja de estilos CSS, ya que ambas formas de salida HTML están basadas en el mismo documento maestro. Esto significa que no hay necesidad de "sincronizar el aspecto" entre dos conjuntos dispares de plantillas y salida HTML. Y, como puede ver, el nuevo HTML de la documentación tiene un ajuste perfecto para la nueva página principal:

Ilustración 1.5: Las nuevas páginas de documentación se adaptan perfectamente a la nueva página principal

La implementación XML

La implementación actual es bien fácil; mi actual sintaxis de la guía XML requiere que cada documento sea parte de un único elemento maestro <guide>. Para añadir soporte a las páginas principales de categorías, creé un nuevo elemento maestro: <mainpage>. Para crear una página principal de categoría, coloqué todo dentro de un elemento <mainpage> en lugar de en un elemento <guide>, y el XSLT hace los cambios apropiados a la salida. Aparte de esto, el único cambio importante requerido es añadir un elemento opcional <sidebar> que es usado para especificar los contenidos de la tabla flotante en una página principal de categoría. La plantilla <guide> XSLT existente tiene este aspecto:

<xsl:template match="/guide">
        <html>
        <head>
                Aquí va el encabezamiento de la guía
        </head>
        <body>
                La parte superior del contenido del cuerpo HTML de la guía va aquí
<!--ahora, insertamos nuestro contenido-->
                <xsl:apply-templates select="chapter" />
                La parte inferior del contenido del cuerpo HTML de la guía va aquí
        </body>
        </html>
</xsl:template>

Si no está muy familiarizado con XSLT, esta plantilla le dice a un procesador XSLT que reemplace las etiquetas <guide> </guide> con el armazón de un documento HTML, así como que aplique recursivamente las plantillas a cualquier elemento <chapter> (abriendo/cerrando pares de etiquetas) dentro del elemento <guide> e insertando la salida resultante en medio del armazón HTML.

Por ello, para añadir soporte a las páginas principales de categorías, necesito especificar que un armazón HTML diferente debería ser usado si todo está encerrado en un único elemento <mainpage>. Para hacer esto, añado una nueva plantilla como sigue:

<xsl:template match="/mainpage">
        <html>
        <head>
                El encabezamiento de mainpage va aquí
        </head>
        <body>
                La parte superior del contenido del cuerpo HTML de la guía va aquí
<!--ahora, insertamos nuestro contenido-->
                <xsl:apply-templates select="chapter" />
                La parte inferior del contenido del cuerpo HTML de la guía va aquí
        </body>
        </html>
</xsl:template>

Ya que casi cada uno de los otros elementos XML (desde <chapter> en adelante) produce salida HTML idéntica tanto para la guía como para las páginas de categorías, casi cada una de las plantillas XSLT puede ser compartida por ambos tipos de páginas. Así, podemos continuar de forma correcta con un único fichero que especifique los dos "armazones HTML" y un conjunto común de plantillas XSLT de XML a HTML. Como siempre la reutilización de código es definitivamente algo bueno.

La página Changelog

Recordará de la parte 2 de esta seria que mencioné que el guión de generación CVS Changelog cvs2cl.pl produce salida XML y que quería usar eventualmente esta característica como base para una página CVS Changelog diaria que aparecería en el nuevo sito Web. Ahora, con este nuevo soporte XML en su lugar, añadiendo la nueva página Changelog era muy fácil. Aquí se muestra una versión mejorada de el guión cvslog.sh que también tiene en cuenta el manejo de la conversión XML-a-HTML:

#!/bin/bash
#various paths
HOMEDIR=/home/drobbins
CVSDIR=${HOMEDIR}/gentoo/gentoo-x86
OUTLOG=${HOMEDIR}/gentoo/xmlcvslog.txt
OUTMAIL=${HOMEDIR}/gentoo/cvslog.txt
WEBDIR=/usr/local/httpd/htdocs
XSLTP=/opt/gnome/bin/xsltproc
TMPFILE=${HOMEDIR}/gentoo/xmlcvslog.tmp
USER=drobbins
#if $CVSMAIL is undefined, set it to "yes"
if [ -z "$CVSMAIL" ]
then
        export CVSMAIL="yes"
fi
#the main script
cd $CVSDIR
cvs -q update -dP
yesterday=`date -d "1 day ago 00:00" -R`
today=`date -d "00:00" -R`
cvsdate=-d\'${yesterday}\<${today}\'
nicedate=`date -d yesterday +"%d %b %Y %Z (%z)"`
#generate cvs2cl.pl XML output
/usr/bin/cvs2cl.pl --xml -f $OUTLOG -l "${cvsdate}"
#use sed to remove "xmlns=" from cvs2cl.pl output
/usr/bin/sed -e 's/xmlns=".*"//' $OUTLOG > ${OUTLOG}.2
#convert cvs2cl.pl XML output to guide format using $XLSTP
$XSLTP ${WEBDIR}/xsl/cvs.xsl ${OUTLOG}.2 > $TMPFILE
#convert guide XML output to HTML format using $XLSTP
$XSLTP ${WEBDIR}/xsl/guide-main.xsl
$TMPFILE > ${WEBDIR}/index-changelog.html
#fix perms
chmod 0644 ${WEBDIR}/index-changelog.html
#automatically send cvs mail if $CVSMAIL is set to "yes"
if [ "$CVSMAIL" = "yes" ]
then
        /usr/bin/cvs2cl.pl -f ${OUTMAIL} -l "${cvsdate}"
        mutt -x gentoo-cvs -s "cvs log for $nicedate" > ${OUTMAIL}
fi

Aunque este guión pueda parecer significativamente más complicado que la versión anterior, realmente solo contiene cuatro o cinco lineas clave adicionales; el resto de las adiciones son bien comentarios, bien definiciones de variables de entorno.

Ahora explicaré cómo las nuevas partes relacionadas con XML del guión cvslog.sh funcionan. Primero, llamamos a cvs2cl.pl y le indicamos que genere un Changelog basado en XML conteniendo todos los ficheros que fueron modificados ayer. Entonces, esta salida XML es ejecutada a través de sed para eliminar cualquier atributo xmlns= innecesario del XML. A continuación, le entregamos este XML ligeramente tocado a xsltproc y le decimos que aplique el procesamiento que se encuentra en cvs.xsl; estas instrucciones transforman la salida XML de cvs2cl.pl en un documento guía XML apropiado. Finalmente, usamos de nuevo xsltproc para convertir este documento guía XML en un HTML preparado para la Web, el cual es inyectado en el directorio htdocs de nuestro servidor Web. La página HTML Changelog generada está completa y este es el resultado:

Ilustración 1.6: La página Changelog automáticamente generada

Se sorprendería de la simplicidad del XSLT contenido en cvs.xsl. En él, especificamos tres plantillas para <changelog>, <entry>, y <file>. También hacemos referencia a unas pocas etiquetas en el fuente XML, incluyendo <date>, <author> y <msg> (los cuales usa cvs2cl.pl para especificar los comentarios del autor del commit en CVS). cvs.xsl hace bastante, considerando que tiene alrededor de 35 líneas de código:

<?xml version='1.0' encoding="iso-8859-1"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output encoding="iso-8859-1" method="xml" indent="yes"/>
<xsl:template match="/changelog">
        <mainpage id="changelog">
        <title>Gentoo Linux Development Changelog for <xsl:value-of select="entry/date"/></title>
        <author title="script">cvs-xml.xsl</author>
        <standout>
                <title>About the Development Changelog</title>
                <body>
                        This page contains a daily Changelog, listing all modifications made to our
                        CVS tree on <xsl:value-of select="entry/date"/> (yesterday).
                </body>
        </standout>
        <version>1.0.0</version>
        <date><xsl:value-of select="entry/date"/></date>
        <chapter>
                <xsl:apply-templates select="entry"/>
        </chapter>
        </mainpage>
</xsl:template>
<xsl:template match="entry">
        <section>
                <title>Files modified by <xsl:value-of select="author"/> at
                                        <xsl:value-of select="time"/>
                </title>
                <body>
                        <note><xsl:value-of select="msg"/></note>
                        <ul>
                                <xsl:apply-templates select="file"/>
                        </ul>
                </body>
        </section>
</xsl:template>
<xsl:template match="file">
        <li><path><xsl:value-of select="name"/></path>, <xsl:value-of select="revision"/></li>
</xsl:template>
</xsl:stylesheet>

¡Proyecto completo!

Desde los comienzos del rediseño del sitio Web Gentoo Linux, hemos creado un plan centrado en el usuario, diseñado un nuevo sistema de documentación basado en XML, un nuevo logo, un nuevo aspecto para el sitio, convertido las partes restantes a XML y añadido una nueva página Changelog basada en XML ¡Uau! Espero que haya disfrutado siguiendo mi progreso y que haya encontrado un abanico de ideas e inspiración a lo largo del camino. He recibido algunas peticiones de más información y código relacionado con el rediseño, por lo que he preparado una página especial Proyectos XML de Gentoo Linux que contiene el más reciente XML, XSLT, guiones y documentación usada para www.gentoo.org. Además de visitar la página de Proyectos, asegúrese de echar un vistazo a los valiosos recursos listados abajo.

2.  Recursos

• Compruebe la página de proyectos XML de Gentoo Linux si está interesado en usar el sistema guide XML de Gentoo Linux como base para sus propios proyectos. Ahí se puede encontrar lo último en materia XML/XSLT.
• Lea los otros artículos de esta serie de developerWorks sobre el rediseño del sitio Web www.gentoo.org usando tecnologías como XML, XSLT, y Python:
  • En la Parte 1, el autor crea un plan centrado en el usuario y presenta pytext, un intérprete incrustado de Python (Marzo 2001).
  • En la Parte 2, Daniel nos muestra el nuevo sistema de documentación y pone en marcha una lista de correo diaria CVS-log (Mayo 2001).
  • En la Parte 3, crea un nuevo aspecto para el sitio (Julio 2001).
• Aprenda más acerca de las hojas de estilo en cascada (CSS) visitando la página CSS en el Consorcio de la World Wide Web o W3C. Puede encontrar más sobre XML, XSLT y muchas más tecnologías igualmente.
• Eche un vistazo a Xara.com, el lugar de Xara X -- un excelente paquete de dibujo vectorial para Windows. Sin apenas grandes pretensiones y una velocidad impresionante, obtiene mi recomendación personal.
• Aprenda incluso más sober XSLT en http://www.xslt.com
• Cuando despierte, pruebe Sablotron, un procesador XSLT bueno y rápido disponible en http://www.gingerall.com