PaGEN - Manual de instalación rápida

Introducción

PaGEN es un sistema generador de páginas web estáticas, útil para los casos donde no se cuenta con un servidor en el que se pueda generar las páginas "al aire" (on-the-fly) y también especialmente útil en los casos donde se requiera generar páginas web y redistribuirlas en un método electrónico no interactivo (en un disco compacto, por ejemplo).

Otros casos donde PaGEN puede ser de relativa utilidad, es para el establecimiento de los servidores espejo ("mirror"), a los que se puede redistribuir el contenido de un sitio completo, sin ninguna restricción de las facilidades que puedan existir en el servidor destino. Es decir, que un sitio generado por PaGEN es plenamente portable y reproducible.

Más información de la forma como funciona PaGEN, así como las razones por las que comencé este proyecto, se pueden encontrar directamente en la página oficial del programa: http://www.geocities.com/larteaga/projects/pagen/.

Resumen

Éste documento trata de cubrir de una manera sencilla la manera de instalar PaGEN versión 1.5 por primera vez en un sistema. Así como el propio programa la documentación todavía está en proceso de continuo mejoramiento y todavía puede contener muchas fallas. Todavía no se provee un proceso de instalación para PaGEN 2.0a, puesto que está en etapa Alpha y todavía no es liberado para entornos productivos.

El software se entrega al usuario final tal como es, y no acepto ninguna responsabilidad por el mal uso del mismo o por estropicios que pudieran ocasionarse por una falla en el código fuente o por la manera como está diseñado. Tampoco prometo dar soporte a la herramienta, pero trataré de contestar de manera adecuada a los mensajes que me hagan llegar acerca de ella.

Requerimientos

Antes de comenzar a instalar PaGEN en su sistema, asegúrese de tener:

• La última versión de PaGEN, disponible en mi repositorio de archivos y programas.
• PostgreSQL funcionando correctamente (ver nota 1).
• Tcl
• La librería libpgtcl.so, generalmente proveída dentro de PostgreSQL, que permite la conexión a la base de datos desde scripts Tcl. En algunas distribuciones GNU/Linux, ésta librería se provee por separado, pero dentro de los mismos discos de instalación. Lea la documentación que acompañaba a su distribución de GNU/Linux.
• Extensiones Tk para Tcl, en caso de querer usar el Editor Rápido de PaGEN (PQE).
• GNU/Linux u otro sistema *nix en el que funcione Tcl/Tk y PostgreSQL (ver nota 2).

El objetivo de este documento no contempla la instalación de GNU/Linux, PostgreSQL ni Tcl/Tk. Éstos tres elementos deben estar en pleno funcionamiento y estado de configuración antes de comenzar a instalar este programa. En caso de dudas, dirigirse directamente a los creadores y personal de mantenimiento de ellos.

Pasos para la instalación

Paso 1: Descomprima el archivo del programa

Obtenga el archivo compreso de PaGEN, en formato tgz. Para descomprimirlo, colóquese en el directorio donde lo guardó al bajarlo y escriba:

% gunzip pagen-1.5.tgz
% tar xvf pagen-1.5.tar

Note que el nombre del archivo pagen-1.5.tgz puede cambiar según la versión que haya bajado del repositorio.

Después de este paso, debería haberse creado automáticamente un directorio pagen directamente debajo del actual.

Paso 2: Lea la documentación proveída

Aunque no está completa, es siempre bueno darle al menos un vistazo a los archivos que componen la raquítica documentación de PaGEN. Dentro del directorio recién creado, hay otro llamado doc. En éste se encuentran los archivos siguientes:

• INSTALL.es.html. Éste archivo.
• ABOUT. Acerca del programa. Todavía en construcción.
• FILES. Como están distribuidos los archivos proveídos.
• INSTALL. Archivo original con instrucciones para la instalación, en inglés.
• README. Léase primero. Todavía en construcción.
• Archivos varios de imágenes usados en las páginas de la documentación.

Por supuesto, siempre supongo que ya se ha leído la página principal de PaGEN, el Manual de Uso y la lista de las Preguntas Frecuentes (FAQ). El Editor Rápido de PaGEN (PQE) tiene su propia página.

Paso 3: Cree la base de datos

Usando el comando dbcreate, hay que crear una base de datos en PostgreSQL. El usuario actual del /shell/ debe tener privilegios suficientes para crear bases de datos nuevas. En caso de errores o dudas, consulte el manual de PostgreSQL.

% createdb pagen
CREATE DATABASE
%

Nota especial: En un mismo sistema puede haber muchas bases de datos. Esto permite de una manera un tanto complicada, tener varios sistemas PaGEN corriendo al mismo tiempo. En la teoría funciona, pero en la práctica resulta engorroso tener varios archivos de configuración, uno por cada copia de PaGEN. La versión 2.0a, incluyendo Snow, el nuevo componente de PaGEN, incluye la característica de tener múltiples "sets" de documentos independientes entre sí residiendo en la misma base de datos.

Ahora, hay que crear las tablas donde estarán almacenados los datos, así como las secuencias y vistas necesarias (ver nota 3). Para no tener que hacerlas a mano, en el directorio sql hay un archivo llamado pg_table_setup.sql. Hay dos formas de ejecutar este archivo: la primera es usando el comando \i desde una sesión de PostgreSQL, pero la que yo prefiero es más sencilla:

% cd pagen/sql
% cat pg_table_setup.sql | psql pagen
CREATE
CREATE
CREATE
CREATE
CREATE
CREATE
CREATE
INSERT 114872 1
INSERT 114873 1
INSERT 114874 1
CREATE
%

Asegúrese de usar el mismo nombre de la base de datos que se especificó en el comando createdb. El resultado del INSERT puede diferir en su sistema, puesto que el número de transacción depende de PostgreSQL.

A medida que se complique la instalación, iré generando un script de instalación para el sistema. Por lo pronto, el archivo install.sh que se provee en el mismo directorio de sql, hace básicamente lo en este paso está expuesto. ¡Cuidado! Este script borra efectivamente la base de datos antes de instalar de nuevo las tablas. Nunca lo use si ya tiene información en ellas, pues lo perderá todo y comenzará en blanco.

Paso 4: Configure el sistema

En el directorio bin hay un archivo llamado pagen.config. Edítelo con su editor de texto de preferencia y cambie los valores de acuerdo a su sistema. Los comentarios de este archivo (y en general de todo el programa, así como los nombres de variables) están en inglés. La sintaxis para las variables es como en Tcl:

set Variable "Valor"

Las variables que se usan están en la siguiente lista. De preferencia --y para mayor referencia--, básese en el archivo pagen.config.sample, en el mismo directorio; este archivo de muestra es el que uso en un sistema HP/UX.

• Clibtcl_location. Lugar donde está la librería libpgtcl.
• Cbase_dir. Directorio donde están localizados los programas (bin).
• Ctmp_content_dir. Directorio de uso exclusivo para PaGEN y PQE, para guardar archivos temporales.
• Ccontent_dir. Directorio donde está el contenido. El programa siempre busca en este directorio archivos de reciente creación o cambio para su inclusión en la base de datos.
• Cmodules_dir. Donde están localizados los módulos externos. (los módulos externos o plug-ins no están en esta documentación).
• Cout_dir. Directorio donde se generarán las páginas. Asegúrese de tener derechos de escritura en el mismo. PaGEN no podrá correr sin ellos.
• Ctheme. Nombre del directorio donde se encuentran los archivos top.html, bottom.html, box.html y sidebox.html y que definen el estilo de la página generada. Algunos temas de ejemplo se incluyen con el archivo de distribución, bajo el directorio theme.
Clang_file. Nombre del archivo de lenguaje. Existen dos posibilidades: lang-english.db y lang-spanish.db. Si usted crea su propio archivo de lenguaje, simplemente especifíquelo en esta variable y póngalo directamente en el directorio apuntado en Cbase_dir.
• Cdatabase. Nombre de la base de datos, según lo especificado en el paso 2, con el comando createdb.
• Cimage_url y Cicon_url. URL que será agregado a los tags img de las páginas generadas.
• Cmax_content. Número máximo de pedazos de texto en una página. Cuando una página tenga más de este número, será dividida automáticamente en las página necesarias, agregando automáticamente un menú de navegación en la parte de arriba de cada una de ellas.
Paso 5: Genere la primera página

Si el sistema quedó bien configurado, a estas alturas podemos generar la primera página. El archivo pg_table_setup.sql incluye una categoría, una página y el primer texto de prueba (que pueden ser cambiados con posterioridad) para acelerar el proceso de instalación.

% cd bin
% ./pagen.tcl -page index
[PRE] Trying the file ./pagen.config
[PRE] Loading configuration file
[PRE] Trying the file /home/lmiguel/pagen-test/pagen/bin/db_lib.tcl
[PRE] Trying the file /home/lmiguel/pagen-test/pagen/bin/pagen.lib
[PRE] Trying the file /home/lmiguel/pagen-test/pagen/bin/lang-spanish.db
18:26:44:main           :PaGEN 1.5 alpha version. [11.09.2002]
18:26:44:Pinitialize    :Cnew_on_site variable not found. Assuming true (1)
18:26:44:main           :Generating pages into /usr/local/httpd/htdocs/pagen-test
18:26:44:Ppage_gen      :Generating page index (/index.html)
18:26:44:Poffset        :Calculating offset of :
18:26:44:Pblock_modules :Adding the block module milchistes.blk
18:26:44:Pupdate_last_mo:Setting last modification time for page index to 20030511182644
18:26:45:Ppage_gen      :End page generation.
18:26:45:Pdb_stats      :12 queries where run.

¡Listo! En el directorio Cout_dir (/usr/local/httpd/htdocs/pagen-test en el ejemplo) deberíamos encontrar la página index.html, la cual se pueder ver con cualquier browser.

Paso 6 (opcional): Configure PQE

Es necesario configura el Editor Rápido de PaGEN (PQE) antes de su primer uso. Edite el archivo pqe.tcl y localize el siguiente pedazo de código, dentro de las primeras líneas del programa:

# Configure this to where your local PaGEN installation is
source "/opt/pagen/bin/db_lib.tcl"
source "/opt/pagen/bin/pagen.lib"

Edite el directorio /opt/pagen/bin/ para que indique donde fué instalado PaGEN.

Uso de PaGEN

Este documento fué creado solamente como una ayuda para la instalación de PaGEN. El uso del programa está definido en la página en el siguiente URL: http://www.geocities.com/larteaga/projects/pagen/man1.html.

El uso de PQE es recomendado para usuarios que se inician con PaGEN. Simplemente, cámbiese al directorio donde fué instalado y edite el archivo pqe.tcl. Luego ejecútelo. Los comandos del menú de PQE son más o menos intuitivos para el usuario acostumbrado a usar otros programas.

% pqe.tcl

Más documentación

Entre otros documentos (todavía en proceso), estarán los siguientes:

• Manual de uso de PQE.
• Manual de uso de PaGEN.
• Versiones en inglés y alemán de todos estos documentos.

Si algún usuario tiene el tiempo y las ganas de escribir estos documentos, mándemelos; que estaré muy contento de agregarlos a la distribución oficial.

Notas finales

(1) En un principio, la idea era que PaGEN no necesitara base de datos alguna para el manejo de contenido, y así fué para las dos primeras versiones. La complejidad creciente del proyecto me obligó a usar una base de datos para acelerar el proceso de generación de las páginas, así como la facilidad de la implementación de código nuevo. Por su buen soporte y excelentes características, elegí PostgreSQL, con mucho la mejor base de datos relacional libre.

(2) Algunos usuarios me han contactado para preguntarme si PaGEN podría funcionar en un sistema con la plataforma Windows de Microsoft. La respuesta ha sido siempre la misma: No tengo la más remota idea. Siento desilusionar a los usuarios de esta plataforma, pero la verdadera razón es que tengo muchos años usarla solamente software libre y no tengo los conocimientos para soportar aquella plataforma. De cualquier manera, cualquier aplicación seria para PaGEN debería ser, en mi particular punto de vista, llevada a cabo en una plataforma *nix.

Extendiendo la respuesta, en teoría tanto Tcl/Tk como PostgreSQL pueden habitar en una máquina corriendo un sistema operativo de Microsoft. Sin embargo, hay al menos un lugar del código de PaGEN que estoy seguro no funcionaría, porque hago llamada a una utilería del sistema operativo (/mkdir/, para crear directorios). Un buen programador podría tratar de usarlo y hacer los pequeños cambios necesarios. Probablemente no sea tan difícil, después de todo.

(3) ¡Cuidado! Algunos nombres de los campos de las tablas cambiaron para la versión 2.0a de PaGEN. La creación de Snow requirió además agregar campos nuevos a la mayoría de las tablas. La actualización de la versión 1.5 (actual) de PaGEN a la 2.0a llevará tiempo y algo de esfuerzo por parte del administrador.