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

{Ttulo: Manual de parsewiki}
{Autor: Jaime E. Villate}
{Organizacin: Universidad de Porto}
{Direccin: [mailto:villate@gnu.org villate@gnu.org] }
{Versin: 0.4}
{Fecha: 11 de abril 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 tambin como ejemplo del tipo de sintaxis que se puede usar \
en el fichero de texto.}

{Copyright: Copyright, 2002 Jaime E. Villate. \
Se otorga permiso para copiar, distribuir y/o modificar este documento \
bajo las condiciones de la Licencia GNU para Documentacin Libre, \
versin 1.1 o posterior, publicada por la ''Free Software Foundation'', \
sin secciones invariantes. Una copia de la licencia se encuentra \
en el fichero GFDL.}

= Introduccin =

El mtodo que proponemos en este manual para producir documentos, tiene como
objetivo facilitarle al usuario la escritura del documento y separar al mximo
el contenido de la presentacin. Basta saber unas pocas reglas de sintaxis
para comenzar a escribir documentos que despus pueden generar varios formatos
diferentes cuando se procesa con '''parsewiki'''.

La ventaja de los sistemas ''wiki'' es permitir que se pueda escribir
rpidamente la versin final, con marcas de formatacin mnimas, de forma casi
tan simple como escribir solo texto. El texto fuente es de muy fcil lectura y
hasta se puede enviar en mensajes de correo, sin asustar a nadie con marcas
extraas. 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 habrn
errores que impidan la formatacin del fichero; puede ocurrir que el resultado
no est formatado como esperabamos, pero nunca habrn errores de sintaxis.
Esta forma de escritura de documentos ha resultado ser muy til en la creacin
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]]) procesndolo con ,,parsewiki,, para
producir una versin HTML:

   parsewiki manual-es.txt > manual-es.html

Despus conviene leer simultamente las dos versiones, comparndolas para
entender como funcionan las reglas de formatacin. Quien sepa como procesar
un fichero ''Docbook/XML'' o ''LaTeX'' para obtener una versin imprimible,
podr tambin 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 lnea debe comenzar en la primera columna. Si dejamos
espacio al comienzo de la lnea, esta ser interpretada como parte de un
listado de programa y ser presentada en forma textual en el fichero de
salida. Las lneas de este prrafo no tienen ningn espacio en blanco inicial,
de manera que sern unidas rellenando los mrgenes del bloque que ocupa el
prrafo; el mismo comportamiento no sera adecuado para un listado de un
programa, siendo preciso insertar espacios al comienzo de cada lnea. 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 prrafo y comenzar otro, dejamos por lo menos una lnea en
blanco. El ttulo de una seccin se escribe entre dos smbolos =, sin dejar
espacio al comienzo de la lnea, pero dejando espacio entre los smbolos = y
el texto del ttulo; por ejemplo:
    = Seccin 1 =

Para subsecciones de varios niveles, se usa ms que un smbolo =; por
ejemplo:
    === Seccin 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 lnea
y no se deben dejar lneas en blanco a menos que se quiera cerrar la lista.
Cuando el contenido de un item sea muy largo podemos cortar una lnea,
colocando un \ al final para indicar que la lnea 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 despus de cada asterisco.
* La lista acaba cuando aparezca una lnea con algo diferente de * en la primera columna.
* Podemos distribuir \
el contenido de cada item en varias \
lneas, si usamos el caracter de continuacin de lnea (\).
Esta parte del texto ya no hace parte de la lista, y ha comenzado un
nuevo prrafo, a pesar de que no hemos dejado lnea 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 ms adelante como incluir una lista dentro de otra.

== Listas descriptivas ==

Son listas con trminos 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
definicin, todo en una misma lnea. 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 cientficos 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 estn 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 nmero de caracteres iniciales.
** En este caso hemos usado 2 asteriscos en vez de uno.
# Aqu continuamos con nuestra lista inicial. Si quisiramos que este\
 item comenzara una nueva lista independiente de la primera, habramos\
 dejado una lnea en blanco.

# Por ejemplo aqu hemos comenzado una nueva lista.
# Que incluir una lista descriptiva:
;;opcin -t: Un fichero con una plantilla que ser usada en vez de la\
 estndar.
;;opcin -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 despus 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 tendrn
que escribir entre [[ y ]]. Por ejemplo, si el documento fuente de este
manual est en el mismo directorio donde ha sido generada la versin HTML,
la pgina HTML tendr un enlace al fichero fuente aqu: [[manual-es.txt]].
O usando algn texto: [[manual-es.txt Fichero fuente de este manual]].

= Figuras =

Si una URL termina con un nombre de fichero con una extensin reconocida
como un formato grfico 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 prrafo 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 algn lugar de la web).
Si asociamos algn 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 debern 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 tambin en maysculas). Si no es as, ser necesario crear una
versin 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 extensin ,,.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
tambin viene en formato PNG (,,barra.png,,). La podremos ver en todos los
formatos de salida as:

[[barra.png]]

La versin PostScript obtenida con ,,latex,, y ,,dvips,,, usar el fichero
,,barra.ps,,. La versin 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 itlica usando dos apstrofos seguidos, o usando una
marca <em> como en HTML: ''as'' o tambin
<em>as</em>. Para letra negrilla
se usan tres apstrofos o la marca <strong>: '''3 comillas''' o
<strong>strong</strong>. Para obtener letra de espacios fijos, como en una
mquina 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
lnea; observando el cdigo fuente de este manual se ver que he usado
ese caracterstica para evitar confusiones cuando escrib la marca <em>
sin una </em> compaera (lo he vuelto a hacer :-). Si el texto es muy largo,
se puede usar el caracter de continuacin de lnea.

= Meta informacin =

Alguna informacin 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 informacin sobre un documento deber estar toda al comienzo, antes
de cualquier otro texto, y cada conjunto {nombre: contenido} debe ocupar
una nica lnea. De lo contrario sera 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 intrnsecamente.
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 opcin
,,-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 fcil y rpida. Debido a su sencillez, no es
posible esperar que se pueda usar el mismo sistema para documentos ms
complicados; sin embargo este mtodo
puede servir como base para crear una versin inicial que despus se puede
volver ms completa trabajando sobre el fichero LaTeX o DocBook creado con
este mtodo.

Esta es una versin beta y por eso probablemente est llena de
errores. Entre los planes inmediatos se encuentran la implementacin de
tablas, bibliografas e figuras con leyendas.