Manual de parsewiki

Jaime E. Villate
Universidad de Porto
villate@gnu.org

versión 0.4

11 de abril de 2002

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.

Introducción

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

Reglas elementales

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 ===

Listas

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.

Listas sin enumerar

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).

Listas enumeradas

  1. Funcionan de forma semejante a las anteriores.
  2. La diferencia es que en vez de *, se usa #.
  3. Ya veremos más adelante como incluir una lista dentro de otra.

Listas descriptivas

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:

HTML
Usado para publicar contenido en la web o para consultar localmente con un navegador web.
XHTML
El lenguaje propuesto para substituir al HTML, con todas las ventajas del XML.
DocBook
Un tipo de documentos XML muy de moda en el mundo editorial.
LaTeX
Sin duda el mejor formato para producir textos científicos de buena calidad.

Listas anidadas

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:

  1. Esta es una lista de nivel 1
  2. Dentro de este segundo item viene una lista de nivel 2:
  3. Aquí continuamos con nuestra lista inicial. Si quisiéramos que este item comenzara una nueva lista independiente de la primera, habríamos dejado una línea en blanco.
  1. Por ejemplo aquí hemos comenzado una nueva lista.
  2. Que incluirá una lista descriptiva:
    opción -t
    Un fichero con una plantilla que será usada en vez de la estándar.
    opción -f
    Formato de salida. Puede ser:
    • html
    • xhtml
    • docbook
    • latex
  3. Aquí termina la lista.

Enlaces (hyperlinks)

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.

Figuras

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 http://savannah.gnu.org/icons/back.png

Si queremos que la figura aparezca aparte del texto, la pondremos dentro de un párrafo separado:

http://savannah.gnu.org/images/floating.jpg

(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:

Logotipo de GNU

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í:

barra.png

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.

Otros tipos de letras

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.

Meta información

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.

Plantillas

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

Conclusiones

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.