Parsewiki es un programa que permite transformar un fichero de texto, con alguna sintaxis simple al estilo Wiki, en varios formatos que incluyen HTML, XHTML, Docbook y LaTeX. Este manual sirve también como ejemplo del tipo de sintaxis que se puede usar en el fichero de texto.
Copyright, 2002 Jaime E. Villate. Se otorga permiso para copiar, distribuir y/o modificar este documento bajo las condiciones de la Licencia GNU para Documentación Libre, versión 1.1 o posterior, publicada por la Free Software Foundation, sin secciones invariantes. Una copia de la licencia se encuentra en el fichero GFDL.
El método que proponemos en este manual para producir documentos, tiene como objetivo facilitarle al usuario la escritura del documento y separar al máximo el contenido de la presentación. Basta saber unas pocas reglas de sintaxis para comenzar a escribir documentos que después pueden generar varios formatos diferentes cuando se procesa con parsewiki.
La ventaja de los sistemas wiki es permitir que se pueda escribir rápidamente la versión final, con marcas de formatación mínimas, de forma casi tan simple como escribir solo texto. El texto fuente es de muy fácil lectura y hasta se puede enviar en mensajes de correo, sin asustar a nadie con marcas extrañas. Otra grande ventaja de este sistema es que no interesa lo que se escriba en el fichero fuente, siempre habrá un fichero de salida. Nunca habrán errores que impidan la formatación del fichero; puede ocurrir que el resultado no esté formatado como esperabamos, pero nunca habrán errores de sintaxis. Esta forma de escritura de documentos ha resultado ser muy útil en la creación de sitios en la web donde cualquier persona puede contribuir, como por ejemplo la enciclopedia Wikipedia.
Para aprender a usar este sistema, se recomienda usar el documento fuente de
este manual (manual-es.txt) procesándolo con parsewiki para
producir una versión HTML:
parsewiki manual-es.txt > manual-es.html
Después conviene leer simultamente las dos versiones, comparándolas para entender como funcionan las reglas de formatación. Quien sepa como procesar un fichero Docbook/XML o LaTeX para obtener una versión imprimible, podrá también usar los siguientes comandos para obtener un fichero Docbook/XML o LaTeX
parsewiki -f docbook manual-es.txt > manual-es.xml parsewiki -f latex manual-es.txt > manual-es.tex
La primera regla que se debe tener en cuenta para escribir un documento
es que el texto en cada línea debe comenzar en la primera columna. Si dejamos
espacio al comienzo de la línea, esta será interpretada como parte de un
listado de programa y será presentada en forma textual en el fichero de
salida. Las líneas de este párrafo no tienen ningún espacio en blanco inicial,
de manera que serán unidas rellenando los márgenes del bloque que ocupa el
párrafo; el mismo comportamiento no sería adecuado para un listado de un
programa, siendo preciso insertar espacios al comienzo de cada línea. Por
ejemplo, una de las subrutinas del programa parsewiki es la siguiente:
sub WikiHeading
{
my ($depth, $text) = @_;
$depth = length($depth);
$depth = 5 if ($depth > 5);
return $OpenItem{'h'.$depth} . $text . $CloseItem{'h'.$depth} . "\n";
}
Para terminar un párrafo y comenzar otro, dejamos por lo menos una línea en blanco. El título de una sección se escribe entre dos símbolos =, sin dejar espacio al comienzo de la línea, pero dejando espacio entre los símbolos = y el texto del título; por ejemplo:
= Sección 1 =
Para subsecciones de varios niveles, se usa más que un símbolo =; por ejemplo:
=== Sección de nivel 3 ===
Existen tres tipos de listas: listas sin enumerar, listas enumeradas y listas descriptivas (glosarios). Cada item en una lista debe ocupar apenas una línea y no se deben dejar líneas en blanco a menos que se quiera cerrar la lista. Cuando el contenido de un item sea muy largo podemos cortar una línea, colocando un \ al final para indicar que la línea continua en la siguiente.
Cada item en una lista sin enumerar debe comenzar por un asterisco (siempre en la primera columna); por ejemplo:
Esta parte del texto ya no hace parte de la lista, y ha comenzado un nuevo párrafo, a pesar de que no hemos dejado línea en blanco en el fichero fuente (opcional).
Son listas con términos seguidos de descripciones, como un diccionario o un glosario. Cada item comienza con un punto y coma (;) en la primera columna, seguido por el termino, seguido por dos puntos (:) y finalmente la definición, todo en una misma línea. Por ejemplo:
Para incluir una lista dentro de otra, se le debe aumentar el nivel a la lista (o las listas) que estén dentro; por ejemplo:
Siempre que se escriba una URL como por ejemplo http://www.usemod.com/cgi-bin/wiki.pl, será reconocida por parsewiki y aparecerá con un enlace a la respectiva URL. Para poder asociar un texto al enlace, se escribe la URL seguida por el texto, dentro de los caracteres [ y ] sin dejar espacio después de [. Ejemplo: tengo mucho orgullo en ser miembro del Proyecto GNU.
Enlaces "internos", con una URL que no comienza por http:// se tendrán
que escribir entre [[ y ]]. Por ejemplo, si el documento fuente de este
manual está en el mismo directorio donde ha sido generada la versión HTML,
la página HTML tendrá un enlace al fichero fuente aquí: manual-es.txt.
O usando algún texto: Fichero fuente de este manual.
Si una URL termina con un nombre de fichero con una extensión reconocida
como un formato gráfico visible por los navegadores web, la URL será
substituida por la imagen (cuando el formato de salida sea HTML o XHTML).
Por ejemplo
Si queremos que la figura aparezca aparte del texto, la pondremos dentro de un párrafo separado:
(Esta figura solo se verá en las versiones HTML y XHTML pues en los otros formatos no se puede mostrar una figura en algún lugar de la web). Si asociamos algún texto a la URL de la figura, en vez de aparecer la figura dentro del documento, obtendremos un enlace a la figura:
Si la figura se encuentra dentro de un directorio local, el camino y nombre
completo deberán ser escritos dentro de [[ y ]]. Es necesario que el nombre de
la figura termine en alguna de las extensiones reconocidas por parsewiki
jpg jpeg png bmp gif
(que pueden ir también en mayúsculas). Si no es así, será necesario crear una
versión en alguno de estos formatos. En el caso de LaTeX producido con
parsewiki, a pesar de que se use uno de estos formatos, se esperará que
exista el mismo fichero pero con extensión .ps o .eps, cuando se use
dvips; si se usa pdflatex en vez, este esperará encontrar la ficheros
terminados en .jpg, .jpeg, .png o pdf.
Con este manual se distribuye una figura vectorial barra.ps que
también viene en formato PNG (barra.png). La podremos ver en todos los
formatos de salida así:
La versión PostScript obtenida con latex y dvips, usará el fichero
barra.ps. La versión PDF producida por pdflatex usará el fichero
barra.png, ya que no existe en este caso un fichero barra.pdf.
Se puede obtener letra itálica usando dos apóstrofos seguidos, o usando una
marca <em> como en HTML: así o también
<em>así</em>. Para letra negrilla
se usan tres apóstrofos o la marca <strong>: 3 comillas o
<strong>strong</strong>. Para obtener letra de espacios fijos, como en una
máquina de escribir, se usan dos comas seguidas o la marca <tt>; por
ejemplo "ls --color".
En los 3 casos el texto en letra diferente debe estar dentro de una única
línea; observando el código fuente de este manual se verá que he usado
ese característica para evitar confusiones cuando escribí la marca <em>
sin una </em> compañera (lo he vuelto a hacer :-). Si el texto es muy largo,
se puede usar el caracter de continuación de línea.
Alguna información opcional sobre el documento puede ser incluida al comienzo, usando la sintaxis: {nombre: contenido}. Si nombre es alguno de los siguientes:
title author date organization address version abstract copyright
el respectivo contenido será usado en la parte inicial del documento. Se puede usar cualquier otro nombre que no esté en la lista, pero su contenido será ignorado, a menos que modifiquemos la plantilla usada normalmente. La meta información sobre un documento deberá estar toda al comienzo, antes de cualquier otro texto, y cada conjunto {nombre: contenido} debe ocupar una única línea. De lo contrario sería procesado como texto normal.
El fichero de salida, en cualquiera de los cuatro formatos que puede producir
parsewiki se crea a partir de unas plantillas definidas por el
propio programa. En el subdirectorio templates que se distribuye
con este programa vienen copias de las 4 plantillas usadas intrínsecamente.
Se pueden usar como modelo para producir otras plantillas diferentes que se
ajuste al formato que queramos producir. Si por ejemplo hemos modificado
la plantilla para LaTeX y la hemos puesto en
~/plantilla.tex la podremos usar por medio de la opción
-t de parsewiki:
parsewiki -f latex -t ~/plantilla.tex fichero.txt > fichero.tex
El sistema simple que hemos documentado en este manual permite crear documentos sencillos de forma fácil y rápida. Debido a su sencillez, no es posible esperar que se pueda usar el mismo sistema para documentos más complicados; sin embargo este método puede servir como base para crear una versión inicial que después se puede volver más completa trabajando sobre el fichero LaTeX o DocBook creado con este método.
Esta es una versión beta y por eso probablemente esté llena de errores. Entre los planes inmediatos se encuentran la implementación de tablas, bibliografías e figuras con leyendas.
