Webon - Software de generacin offline de catlogos Web
=======================================================

 Angel Ortega <angel@venexma.es>

ESTA DOCUMENTACIN EST EN DESARROLLO. LO QUE AQU SE DESCRIBE PUEDE SER
INCOMPLETO, INCORRECTO O SIMPLEMENTE MENTIRA.

Webon es un programa para facilitar la creacin de catlogos de artculos
para publicacin en el World Wide Web de forma offline, es decir,
construyendo pginas estticas que se publicarn mediante transferencia
directa sin necesidad de ejecutar cdigo en el servidor Web.

Webon se dise especficamente para la construccin de la pgina Web
http://www.venexma.es, propiedad de la empresa Venexma Europa, S.L. Por
tanto, parte de su cdigo est diseado para cubrir necesidades
especficas de la empresa que con toda seguridad no sern tiles para el
resto del mundo; no obstante, el cdigo est siendo mejorado para separar
esas funcionalidades especficas del resto del cdigo que podra ser til
a terceros.

Webon est escrito en Perl y utiliza los mdulos Template Toolkit y
Getopt::Long. Todos sus datos los toma de ficheros de texto.

La documentacin que sigue a continuacin no describe el comportamiento
del software en su versin actual, sino el modelo deseado para la
versin 'definitiva'; no obstante, las diferencias sern probablemente
pequeas.

Modelo
------

Cada proyecto gestionado por Webon requiere un directorio de trabajo con
la siguiente estructura:

 ./catalog
 ./arts/
 ./img/
 ./th/
 ./lang/
 ./pages/
 ./raw/
 ./templates/
 ./output/

La unidad organizacional de Webon es el artculo o, ms concretamente, el
identificador del artculo. ste es una cadena de caracteres con el
siguiente formato:

 rama-subrama-subsubrama_nombre

Las subramas son opcionales y deben ir separadas entre s por - (guiones).
El nombre del artculo va separado del resto por un _ (subrayado). Cada
elemento debe estar formado por caracteres alfanumricos, y por comodidad
es recomendable que sean cortos. El componente 'nombre' ser utilizado
para una ordenacin alfabtica en la pgina ndice de la rama.

Creacin de una estructura bsica
---------------------------------

Por ejemplo, supongamos que tenemos una rama Herramientas, con una subrama
Martillos, y que en ella vamos a incluir dos artculos, el "Martillo
Pequeo" y el "Martillo Luis XV". Para ello, inventaremos un nombre corto
para la rama Herramientas ('herr') y otro para la subrama Martillos
('herr-mar'). Dentro de ella, cada tipo de martillo recibir un nombre
nico, que aqu pondremos como valores numricos, quedando as:

 herr-mar_001
 herr-mar_002

Para que estas ramas sean tenidas en cuenta en el momento de la
construccin, debern ser aadidas al fichero de catlogo (por defecto,
catalog). Este fichero contiene simplemente una lista de ramas, una en
cada lnea. El orden no es importante, pero s deben aadirse
explcitamente ramas y subramas. El contenido sera el siguiente:

 herr
 herr-mar

A continuacin necesitaremos dar nombre a las ramas y a los artculos.
Para ello, deberemos crear una entrada para cada uno de ellos en cada uno
de los ficheros de idiomas que aparecen en el directorio de idiomas (por
defecto, ./lang). Estos ficheros contienen lneas en el formato

 identificador: cadena de texto en el idioma correspondiente

Suponiendo que queramos mantener el catlogo en espaol e ingls,
deberemos tener dos ficheros de traduccin, a los que llamaremos 'es' para
espaol y 'en' para ingls, utilizando los cdigos estndar de dos letras
para nombres de idiomas.

As, el fichero lang/es quedara de la siguiente forma:

 herr: Herramientas
 herr-mar: Martillos
 herr-mar_001: Martillo pequeo
 herr-mar_002: Martillo "Luis XV"

Y el fichero lang/en:

 herr: Tools
 herr-mar: Hammers
 herr-mar_001: Small hammer
 herr-mar_002: "Louis XV" hammer

A continuacin, necesitamos crear una entrada para los artculos en s
mismos. Esto se har creando un fichero para cada artculo en el
directorio de artculos (por defecto, ./arts). Como cabe esperar, cada
nombre del fichero ser el correspondiente a cada artculo, a saber

 ./arts/herr-mar_001
 ./arts/herr-mar_002

Como de momento no queremos aadir ningn contenido a cada artculo, se
pueden crear con el contenido por defecto:

 [% INCLUDE art_GENERIC %]

Los ficheros de artculos pueden tener marcas del Template Toolkit 
cdigo HTML.

Por ltimo, asociaremos al menos dos imgenes al artculo: el icono 
'thumbnail' que aparecer en la pgina ndice de la rama, y la imagen ms
grande, que aparecer en la pgina propia del artculo.

Las imagenes utilizan una nomenclatura semejante a la vista hasta ahora,
pero con una extensin a modo de sufijo para asociar mltiples imgenes a
un mismo artculo. As, una imagen deber llamarse

 rama-subrama-subsubrama_nombre-secuencia.jpg

Donde la secuencia es un nmero. No es necesario que existan, pero de ser
as, deben empezar por 1 y ser secuencias completas sin saltarse ningn
nmero. Todas las imgenes sern includas en la pgina del artculo, por
orden numrico. Las imgenes deben residir en el directorio ./img.

Respecto a los 'thumbnails', la nomenclatura es la misma, aunque en la
versin actual slo se utiliza el n 1, que es obligatorio para cada
artculo. Deben estar almacenados en el directorio ./th. Unas dimensiones
de 128x128 pxels suelen ser adecuadas, aunque depender del cdigo HTML y
de la hoja de estilo utilizado. Es recomendable que todos los 'thumbnails'
de una rama tengan la misma proporcin.

De momento, slo estn soportados los archivos con extensin .jpg.

Siguiendo con nuestro ejemplo, haremos unas elegantes fotos de nuestros
martillos y las guardaremos con los siguientes nombres:

 ./img/herr-mar_001-1.jpg
 ./img/herr-mar_002-1.jpg

y, debidamente redimensionadas a un tamao razonable de 128x128 pxels,
crearemos copias en

 ./th/herr-mar_001-1.jpg
 ./th/herr-mar_002-1.jpg

Si nuestro martillo Luis XV requiere especial atencin y merece una
segunda foto desde otra perspectiva, la guardaremos con el nombre

 ./img/herr-mar_001-2.jpg

Limitaciones conocidas
----------------------

Efectivamente, el criterio de organizacin utilizado ancla cada artculo
forzosamente a una nica posicin en el catlogo. Y s, es una limitacin
importante, convirtiendo en engorroso el proceso de recolocar un artculo
en otra rama diferente y haciendo poco menos que imposible tener un mismo
artculo en ms de una rama sin recurrir a apas.

La reubicacin de artculos se puede resolver creando un script para ello.

Respecto a la aparicin de un artculo en ms de un rama, existe en la
actualidad una caracterstica experimental que permite asignar
'ubicaciones secundarias' para artculos concretos. Aunque funciona
correctamente, no est en uso debido a que falta una caracterstica
esencial: la generacin de mltiples trayectorias de 'migas de pan' segn
cada una de las ramas de las que cuelga cada artculo.

Sobre el rendimiento y las transferencias de red
------------------------------------------------

Por su naturaleza 'offline', Webon est diseado para optimizar el ancho
de banda de la transferencia en detrimento de otros factores como potencia
de proceso  espacio en disco.

En el proceso de construccin, Webon recorre todos y cada uno de los
artculos y los construye mediante Template Toolkit, para despus comparar
el resultado obtenido con el contenido ya almacenado en disco de una
(posible) construccin anterior. Slo se escribe en disco si el contenido
difiere. Esto permite usar sistemas basados en 'timestamp' como ftp por
lotes  rsync para optimizar las transferencias de red a costa de unos
requerimientos ms altos de CPU en el momento de la construccin.

Se estudi utilizar el 'timestamp' de cada artculo como indicativo de la
necesidad de construccin (como hara, por ejemplo, la herramienta make)
en lugar de reconstruirlos todos, pero habra que tener adems en cuenta
otros factores como el cambio de alguna de las cadenas de traduccin (en
el nombre del artculo o en el cuerpo del mismo), la posible adicin de
imgenes nuevas, etc.

Plantillas especiales
---------------------

 * art_INDEX: Plantilla para el superndice (ndice global o pgina de
   entrada).
 * art_index: Plantilla para el ndice de cada rama.
 * art: Plantilla para cada artculo.
 * page: Plantilla para las pginas de contenido libre.

---
Angel Ortega <angel@venexma.es>
