htmlex - un poderoso preprocesador del lenguaje de marcado de hipertexto (HTML) Copyright (C) 2001, 2002, 2003 por David A. Capello LICENCIA ======== htmlex es software libre; usted puede redistribuirlo y/o modificarlo bajo los términos de la Licencia Pública General GNU (o GNU General Public License) publicada por la Fundación de Software Libre (Free Software Foundation); cualquier versión 2 de la Licencia, o (a su elección) alguna versión más antigua. Este programa es distribuido con la esperanza de que sea útil, pero SIN GARANTÍA ALGUNA; sin incluso la garantía implícita de COMERCIALIZACIÓN o IDONEIDAD PARA UN PROPÓSITO PARTICULAR. Vea la GNU General Public License para más detalles. Usted debe de haber recibido una copia de la GNU General Public License junto con este programa; si no, escriba a la Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA INTRODUCCIÓN ============ htmlex es un pequeño pero poderoso preprocesador de ficheros HTML, con el cual podrá tener varias ventajas con respecto al formato convencional de los archivos .html. Además, como htmlex es completamente compatible con la sintaxis HTML estandard, significa que cualquier archivo que ya haya creado en HTML puro, lo podrá renombrar tranquilamente a .htex. OPCIONES ======== htmlex interpreta las siguientes opciones en la línea de comandos: -c compila todos los próximos ficheros (obtiene un archivo de salida desde "-o" o genera un nombre con extension .html, mire -E) -o agrega ficheros de salida -a agrega argumentos a los archivos de entrada -I agrega rutas de inclusión para búscar ficheros -E cambia la extensión HTML utilizada por la opción -c (.html por defecto) -k elimina los comentarios (comportamiento antiguo de htmlex) -d calcula las dependencias de los ficheros de entrada (salida hacia STDOUT) -v activa el modo verboso (para ver que hace htmlex) -V activa el modo muy verboso (para depurar archivos .htex) -h muestra esta ayuda (en inglés) y sale -- frena los argumentos -coaI EJECUCIÓN ========= Referencias ----------- STDIN Entrada estandard: desde el teclado o desde un fichero. STDOUT Salida estandard: hacia la pantalla o hacia un fichero. Conducta común -------------- ./htmlex Procesa STDIN y deja los resultados en STDOUT. ./htmlex archivo argumentos... Procesa el `archivo' y deja el resultado en STDOUT. ./htmlex -c archivos... -a argumentos... Procesa los `archivos' y deja los resultados en `archivos.html'. ./htmlex -c archivos... -o destinos... ./htmlex -o destinos... -c archivos... Procesa los `archivos' y deja los resultados en los `destinos'. Algunos ejemplos de equivalencias --------------------------------- ./htmlex fichero.htex arg1 arg2 > fichero.html ./htmlex -c fichero.htex -a arg1 arg2 ./htmlex -c fichero.htex -o fichero.html -a arg1 arg2 ./htmlex -a arg1 arg2 < fichero.htex > fichero.html ./htmlex -a arg1 arg2 -o fichero.html < fichero.htex Errores comunes --------------- ./htmlex -I ejemplos archivo.htex > archivo.html Aquí el programa esperará la entrada de STDIN, ya que archivo.htex cuenta como otra ruta más para "-I". Posibles soluciones: ./htmlex -I ejemplos -- archivo.htex > archivo.html ./htmlex -I ejemplos -c archivo.htex ./htmlex archivo.htex -I ejemplos > archivo.html ./htmlex -c index.htex es Español Aquí se intentará compilar los ficheros `index.htex', `es' y `Español', en vez de pasarle los argumentos al fichero `index.htex'. Posibles soluciones: ./htmlex -c index.htex -a es Español ./htmlex index.htex es Español > index.html Cambios con respecto a versiones anteriores ------------------------------------------- * Ahora puede utilizar "-I" en vez de "-i" (como en gcc). * Desde ahora el orden de los argumentos no es necesario, por lo que puede hacer cosas como: ./htmlex -c orig.htex -o dest.html -I dir CARACTERÍSTICAS =============== Referencias ----------- Esta notación se usará a lo largo de las definiciones: expresión La _expresión_ es obligatoria. [ expresión ] La _expresión_ es opcional, puede o no estar. { expresión } La _expresión_ puede no estar o puede repetirse una o más veces. origen -> resultado Indica que _resultado_ será obtenido al procesar mediante el programa el texto de _origen_. Etiquetas --------- Lista de las etiquetas que puede utilizar en los ficheros .htex (por orden alfabético): Devuelve la cantidad de argumentos que se le pasaron al fichero de entrada. Es igual a 0 si no se le pasó ningún parámetro. Ejemplo: A ingresado argumento(s). ... Retornan el valor del argumento indicado. Los argumentos se le pasan a los ficheros a través de la línea de comandos con la opción -a o por medio de la etiqueta . Ejemplo: 2do argumento = . Devuelve el nombre base del _fichero_, es decir, le saca la extensión. Ejemplos: -> src/foo -> src-1.0/bar -> hacks Le quita el último carácter a la _palabra_. Ejemplos: -> eco -> directorio Limpia la _palabra_ quitándole los espacios (tabuladores y retornos de líneas) que tenga al inicio y al final. Ejemplo: ** -> *hola* Agrega como dependencia el `fichero'. Como es de esperarce, esta etiqueta tiene efecto sólo en el proceso de generación de dependencias. Ejemplo: Devuelve el directorio del _fichero_, es decir, le saca nombre. Ejemplos: -> src/ -> a/b/ -> ./ Ver . Ver . Ver . Ejecuta el _fichero_ indicado pasándole los _argumentos_. Lo que el comando imprima por la salida estandard (STDOUT), será insertado tal cual en el resultado. Ejemplos: Igual que solamente que éste procesará los resultados como a otro fichero htmlex. Ejemplos: > Ver . Devuelve el tamaño del _fichero_ en bytes, kilo-bytes (k) o mega-bytes (M) dependiendo de cual sea mejor para la "vista humana". Ejemplo: imagen Intentará encontrar el _fichero_ en todas las ubicaciones posibles (en el directorio actual y en los directorios indicados con -i), y devolverá el nombre del mismo con la ruta de acceso correspondiente, en caso de que el _fichero_ no se pueda encontrar, no devuelve nada. Ejemplos: > español Crea una nueva macro funcional al estilo C/C++. El programa al ver esta etiqueta, sigue leyendo el archivo de forma "cruda" hasta encontrar la etiqueta . Luego, la macro puede ser llamada como cualquier otra etiqueta: . Ejemplo: a es b c . Resulta en: Esta es mi macro. Una de las más poderosas características que tiene htmlex con respecto al HTML convencional, es la posibilidad de controlar bloques de condiciones. Por medio de cuatro etiquetas podrá hacer la mayoría de operaciones de condición de cualquier otro lenguaje de programación. Aunque hoy en día, htmlex posee un pobre manejo de operaciones, en el futuro tal vez se intente mejorar este aspecto. La sintaxis general es la siguiente: bloque { bloque } [ bloque ] Los _bloques_ pueden ser cualquier texto (o simplemente nada), hasta pueden tener otras etiquetas a su vez, y por consiguiente, puede tener más etiquetas anidadas. En cuanto a las _expresiones_ para realizar las comparaciones, pueden tener estos formatos (en caso contrario siempre dará falso): FORMATO VERDADERO SI... ------- --------------- número _número_ es distinto a cero ! número _número_ es cero palabra _palabra_ tiene un caracter como mínimo ! palabra _palabra_ está vacía número1 < número2 _número1_ es menor a _número2_ número1 > número2 _número1_ es mayor a _número2_ número1 <= número2 _número1_ es menor o igual a _número2_ número1 >= número2 _número1_ es mayor o igual a _número2_ número1 == número2 _número1_ es igual a _número2_ número1 != número2 _número1_ es diferente a _número2_ palabra1 == palabra2 _palabra1_ es idéntica a _palabra2_ palabra1 != palabra2 _palabra1_ difiere en un caracter a _palabra2_ Los _números_ se distinguen de las _palabras_ cuando tiene alguno de los siguientes formatos: [1-9][0-9]* un decimal 0x[0-9a-fA-F]* un hexadecimal 0[0-7] un octal Ejemplos: == --help> ¿Necesita ayuda? Pruebe con --help. == > funciona Por acá nunca pasará Incluye el _fichero_ para que sea procesado como un archivo .htex. Dicho archivo será utilizado también para calcular las dependencias (cuál archivo necesita de qué otro). Ejemplos: Crea y/o modifica una macro con el _nombre_ y el _valor_ especificado. Si el _valor_ no se indica, la macro será eliminada de la memoria. La utilidad principal de las macros, es reemplazar un determinado texto (su _nombre_) por otro determinado texto (su _valor_). Ejemplo: hola -> chau hola -> hola Borra de la memoria cualquier macro que se haya creado con anterioridad a esta etiqueta. Ejemplo: aa -> ba Devuelve el nombre del _fichero_ a secas, es decir, le saca el directorio. Ejemplos: -> foo.c -> foo.h -> hacks Le quita el primer carácter a la _palabra_. Ejemplos: -> ola -> txt Devuelve el sufijo del _fichero_, es decir, su extensión. Ejemplos: -> .c -> -> Ver . Pasa parcial o completamente la _palabra_ a minúsculas o mayúsculas dependiendo si especifica o no el _comienzo_ y/o el _final_. Si indica solamente el _comienzo_, el mismo deberá ser un índice (con base cero, es decir, 0 es la primer letra) del caracter que quiere convertir, mientras que si también indica el _final_, está diciendo que quiere convertir todo un rango. Nota: valores negativos para _final_ indican valores desde el mismo final de la _palabra_. Ejemplos: -> hola -> hOLA -> hOLa -> HOLa Muestra la versión del programa con la que se está procesando el fichero. Ejemplo: Está página fue creada con htmlex . NOTAS IMPORTANTES ================= borra la macro X, por lo que si utiliza la expresión dá verdadero (ya que se utiliza la cadena "X" y no el valor de X). le asigna a la macro X un valor nulo, esto es necesario para que dé falso (ya que en este caso, X sí es reemplazado por su valor). FALLOS ====== Comunicar `bugs' y errores a . ACTUALIZACIONES =============== Para obtener la última información sobre htmlex, puede dirigirse a: http://htmlex.sourceforge.net AUTOR ===== David A. Capello Cualquier sugerencia, agradeciemiento, y, con preferencia, donación ;-), será bien recibida. Puede visitar http://www.davidcapello.com.ar para mayor información.