{Título: Manual de parsewiki}
{Autor: Jaime E. Villate}
{Organización: Universidad de Porto}
{Dirección: [mailto:villate@gnu.org villate@gnu.org] }
{Versión: 0.5}
{Fecha: 8 de junho de 2002}
{Idioma: es}

{Resumen: 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: Copyright (C) 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.}

{CVS: $Id: manual-es.txt,v 1.8 2002/04/11 19:51:40 villate Exp $ }

= 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 [http://www.wikipedia.com 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 simultáneamente 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:
* Se puede dejar o no espacio después de cada asterisco.
* Cada ítem en una lista debe ocupar una única línea. Para hacer que \
varias líneas sean consideradas como una única, usamos el signo de \
continuación de línea (\) al final de cada línea.
* La lista acaba cuando aparezca una línea con algo diferente de * en la \
primera columna.
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 ==

# Funcionan de forma semejante a las anteriores.
# La diferencia es que en vez de *, se usa #.
# 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:

# Esta es una lista de nivel 1
# Dentro de este segundo item viene una lista de nivel 2:
** El nivel se aumenta aumentando el número de caracteres iniciales.
** En este caso hemos usado 2 asteriscos en vez de uno.
# 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.

# Por ejemplo aquí hemos comenzado una nueva lista.
# 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
# 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 [http://www.gnu.org 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: [[manual-es.txt 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:

[http://www.gnu.org/graphics/gnu-head-sm.jpg 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.