PageRenderTime 68ms CodeModel.GetById 16ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/Spanish/userguide-es/userguide-es.t2t

http://txt2tags.googlecode.com/
Unknown | 1927 lines | 1271 code | 656 blank | 0 comment | 0 complexity | 873c13a688e736773604a60bc5c4c5c7 MD5 | raw file
Possible License(s): GPL-2.0, GPL-3.0, WTFPL
  1. Txt2tags: Guia del Usuario de Txt2tags
  2. Aurelio, %%mtime(%c)
  3. Traducción al espańol: Antoni Serra Devecchi
  4. %!target: html
  5. %!options: --toc --toc-level 2 --css-sugar
  6. %%!options: -o ../../../web/userguide/userguide.html
  7. % TRANSLATOR:
  8. % - Don't worry about the PDF cover page
  9. % - Don't worry about PDF at all, translate and check on HTML
  10. % - Don't worry about the images
  11. % TRANSLATOR uncomment the next line
  12. %%!options: -o userguide.html
  13. % TRANSLATOR uncomment the next line to use images on the same folder
  14. %!preproc: IMGPATH .
  15. % TRANSLATOR:
  16. % You can take new screenshots and make new images for the program
  17. % interface and "first conversion" section. Remember to send them
  18. % to the author!
  19. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  20. %%% activate those lines when converting to HTML for PDF generation
  21. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  22. %%% htmldoc does TOC
  23. %!options(html): --no-toc --no-css-sugar -o userguide-pdf.html
  24. %%% mask the 'nopdf' marks so they will not be removed
  25. %!preproc(html): ^%nopdf %yespdf
  26. %%% removing first header, htmldoc ignores all until next <H1> (cool!)
  27. %!postproc(html): '<H1>Txt2tags: .*</H1>' ''
  28. %%% imagens are in the same dir
  29. %!preproc: IMGPATH .
  30. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  31. % easy way to change all image locations once, when changing file location
  32. %!preproc: IMGPATH ../img
  33. % normalizing common text
  34. %%!preproc: CONFAREA Config Area
  35. %%!preproc: HEADAREA Header Area
  36. %%!preproc: BODYAREA Body Area
  37. %%!preproc: MARKPROP **Properties:**
  38. %%!preproc: MARKCONT **Contains:**
  39. %%!preproc: MARKDESC **Description:**
  40. %%!preproc: MARKSYN **Syntax:**
  41. %%!preproc: MARKDET **Details:**
  42. %%!preproc: NOMARKS Marks are NOT interpreted
  43. %%!preproc: NOMACRO Macros are NOT interpreted
  44. %!preproc: URLMARKUP http://txt2tags.org/markup.html
  45. % activate the areas disabled on the PDF version
  46. %!preproc(html): ^%nopdf ''
  47. % remove separator lines and strong lines
  48. %!preproc(html): '^ *--------*' ''
  49. %!preproc(html): '^ *========*' ''
  50. % highlight NEW topic on TOC
  51. %%!postproc(html): '(<LI>.*Mastering Macros</A>)$' '\1 <b>[NEW!]</b>'
  52. %%% Little clean up for less large tables
  53. %!postproc: /pessoal/sourceforge.net ''
  54. % border for all images
  55. %!postproc: '(<IMG [^>]*BORDER)="0"' '\1="1"'
  56. %%% Embedded CSS code (ugly not?)
  57. %
  58. %!postproc(html): ^<HEAD>$ '<HEAD>\n<STYLE TYPE="text/css">\n@#@'
  59. %!postproc(html): (@#@)$ 'body {background-color:#ddeeff; color:black; \n\1'
  60. %!postproc(html): (@#@)$ ' margin:3em; text-align:justify;} \n\1'
  61. %!postproc(html): (@#@)$ '#header {text-align:center;} \n\1'
  62. %!postproc(html): (@#@)$ '.toc {border:1px solid black;padding:9px;\n\1'
  63. %!postproc(html): (@#@)$ ' background-color:white;} \n\1'
  64. %!postproc(html): (@#@)$ '.toc li{list-style-type: none;} \n\1'
  65. %!postproc(html): (@#@)$ 'a {text-decoration:none;}\na:hover {color:red;}\n\1'
  66. %!postproc(html): (@#@)$ 'a:visited {color:purple;}\ndl {margin:1em;} \n\1'
  67. %!postproc(html): (@#@)$ '#body h1 {text-align:center; color:white; \n\1'
  68. %!postproc(html): (@#@)$ ' background-color:blue; padding:8px;} \n\1'
  69. %!postproc(html): (@#@)$ 'h2 {padding-top:20px;}\nhr {border-style:none;}\n\1'
  70. %!postproc(html): (@#@)$ 'code {background-color:lightblue;} \n\1'
  71. %!postproc(html): (@#@)$ 'blockquote {border:1px solid black;padding:9px;\n\1'
  72. %!postproc(html): (@#@)$ ' background-color:white;} \n\1'
  73. %!postproc(html): (@#@)$ 'table {border-style:solid; border-color:black;}\n\1'
  74. %!postproc(html): (@#@)$ 'th {background-color:lightblue; padding:.5em;} \n\1'
  75. %!postproc(html): (@#@)$ 'td {border-style:none; background-color:white;}\n\1'
  76. %!postproc(html): (@#@)$ 'pre {border-style:solid; border-width:1px 1px; \n\1'
  77. %!postproc(html): (@#@)$ ' background-color:lightblue; padding:8px; \n\1'
  78. %!postproc(html): (@#@)$ ' border-color:black;} \n\1'
  79. %!postproc(html): @#@$ </STYLE>
  80. % 26/Nov/2003: revised by anamimts
  81. % 26/Jun/2004: updated to v2, new embedded CSS
  82. % 17/Jul/2004: revised by anamimts
  83. % 01/Nov/2004: updated to v2.0 and 2.1, new chapters, PDF version
  84. % TODO Mastering Options [option-help], [option-css-sugar], ...
  85. ========================================================================
  86. %nopdf "ĄHola! Čsto es la Guia del Usuario de Txt2tags. Aquí podrás encontrar
  87. %nopdf toda la información disponible sobre la herramienta de conversión de textos txt2tags.
  88. %nopdf Puedes encontrar la última versión en http://txt2tags.org/userguide/.
  89. %nopdf Para más información, visita la
  90. %nopdf [web de txt2tags http://txt2tags.org]. ĄQue disfrutes!"
  91. %nopdf
  92. %%nopdf [Download PDF version http://txt2tags.org/userguide/userguide.pdf]
  93. ========================================================================
  94. %nopdf%**This Guide Contains:**
  95. %%toc
  96. ========================================================================
  97. = Parte I - Introducción a Txt2tags =[intro]
  98. == Tus Primeras Preguntas ==[1st-questions]
  99. Este capítulo presenta txt2tags, introduciendo a las funcionalidades y objetivos del programa.
  100. ------------------------------------------------------------------------
  101. === żQue és Txt2tags? ===
  102. Txt2tags es una herramienta de formateo y conversión de texto.
  103. Txt2tags convierte un archivo de texto con algunas marcas a uno de los siguientes tipos de archivo:
  104. - Documento HTML
  105. - Documento XHTML
  106. - Documento SGML
  107. - Documento LaTeX
  108. - Página man de UNIX
  109. - Presentación Magic Point
  110. - Página MoinMoin
  111. - Documento PageMaker 6.0
  112. - Texto plano (sin marcas)
  113. ------------------------------------------------------------------------
  114. === żPor Qué Debo Usar Txt2tags? ===
  115. Encontarás txt2tags muy útil si:
  116. - precisas publicar documentos en diferentes formatos
  117. - precisas mantener documentos actualizados en diferentes formatos
  118. - escribes manuales o documentos técnicos
  119. - no sabes como escribir un documento en un formato específico
  120. - no posees un editor específico para cierto formato
  121. - quieres usar un editor de texto simple para actualizar tus documentos
  122. Pero la motivación principal es:
  123. - economizar tiempo,escribiendo **contenido** sin preocuparse del **formato**
  124. ------------------------------------------------------------------------
  125. === żQué ventajas ofrece, comparado con otras herramientas? ===
  126. Txt2tags se encuentra en constante crecimiento, siguiendo una serie de conceptos basicos:
  127. | //Archivo fuente legible// | Las marcas de txt2tags son muy simples, casi naturales
  128. | //Documento destino legible// | Como el archivo fuente, el código del documento generado es también legible
  129. | //Consistencia en las marcas// | Las marcas txt2tags son únicas, atendiendo todos los tipos de documentos, sin ser confundidas con el contenido
  130. | //Reglas consistentes// | De la misma manera que las marcas, las reglas a ellas aplicadas son uniformes, sin excepciones ni casos especiales..
  131. | //Estructuras simples// | Todas las estructuras soportadas son simples, sin opciones extras o modificadores complejos del comportamiento. Una marca es solo una marca, sin opciones adicionales.
  132. | //Facil de apreder// | Con marcas simples y código fuente legible, presenta una curva de aprendizaje muy amigable.
  133. | //Buenos ejemplos// | Los **archivos de ejemplos** incluidos en el paquete están basados en documentos reales, son simples, bién estructurados y están escritos en formato txt2tags.
  134. | //Herramientas valiosas// | Los **archivos de sintaxis**, incluidos en el paquete ( para los editores Vim, Emacs, Nano y Kate) ayudan a escribir documentos sin errores sintácticos.
  135. | //Tres interfaces de usuario// | Tiene una **interfaz Gráfica Tk**, una **interfaz Web**, que permite usar el programa remotamente o através de una intranet, y una **interfaz en línea de comandos** para usuarios avanzados y scripts.
  136. | //Soporta scripts// | Con el modo completo de línea de comandos, un usuario avanzado puede automatizar tareas y efectuar post-ediciones en los archivos convertidos.
  137. | //Descargar y Ejecutar / Multiplataforma// | txt2tags es un **script Python**. No hay necesidad de compilarlo o cargar módulos extra.Puede ser ejecutado sin problemas en máquinas UNIX, Linux,Windows y Macintosh .
  138. | //Actualizaciones Frecuentes// | El programa posee una lísta de discusión con usuarios activos que suguieren correcciones y mejoras. El propio autor es un usuario "intensivo" en casa y en su trabajo, por lo que es difícil que el desarrollo pare.
  139. ------------------------------------------------------------------------
  140. === ż Cuanto cuesta ? ===
  141. || ĄABSOLUTAMENTE NADA! |
  142. Txt2tags es un programa gratuito,GLP,open source,dominio público,etc...
  143. %//<put-your-favorite-buzzword-here>//.
  144. Puedes copiarlo,usarlo,modificarlo,venderlo.. etc. Las polítcas de software y copyright no se encuentran entre las mayores preocupaciones del autor.
  145. ------------------------------------------------------------------------
  146. == Estructuras de Formato Soportadas por txt2tags ==[structures]
  147. - Encabezamiento (Cabeceras) ( título del documento, nombre de autor,fecha)
  148. - Títulos de secciones (numeradas o no)
  149. - Parráfos
  150. - Modificadores de fuentes
  151. - Negrita (bold)
  152. - Itálica
  153. - Subrayada
  154. - Fuente no proporcional (Monoespaciada/Verbatim)
  155. - Monoespaciada en un párafo
  156. - Línea monoespaciada
  157. - Zona en monoespaciado (multilínea)
  158. - Cítas
  159. - Enlaces
  160. - URL/ enlaces internet
  161. - enlaces e-mail
  162. - enlaces locales
  163. - enlaces nombrados
  164. - Listas
  165. - listas marcadas
  166. - listas numeradas
  167. - listas de definicion
  168. - Líneas de separación horizontal
  169. - Imágenes (con un alineamiento adecuado)
  170. - Tablas (con o sin borde,con alineamiento , con expansión de columna)
  171. - Marcas especiales para texto raw ( que no debe ser tratado)
  172. - Macro especial para la fecha actual (con formato flexible)
  173. - Comentarios (para notas,TODO,FIXME,etc)
  174. ------------------------------------------------------------------------
  175. == Formatos de salida soportados ==[targets]
  176. : **HTML**
  177. Todos sabemos lo que es HTML.
  178. Txt2tag genera documentos HTML límpios, con una buena presentación y cuyo código fuente es legible. No utiliza javascript, frames u otras técnicas fútiles,frecuentemente innecesarias en el formateo de documentos técnicos. Pero, si se desea, puede utilizarse un archivo CSS externo.
  179. Txt2tag genera código "//HTML 4.0 Transitional//".
  180. Desde la versión 2.0 de txt2tags el código HTML generado es aprobado al 100%
  181. por el [ validador w3c http://validator.w3.org/].
  182. : **XHTML**
  183. Es la nueva generación de HTML con reglas mas estrictas, como la de tener que cerrar todas las marcas que se abran. De esta manera se consigue un código más fácil de tratar y de entender. Para propósitos generales, se puede considerar como HTML.
  184. Txt2tag genera código "XHTML 1.0 Transitional".
  185. Desde la versión 2.0 de txt2tags el código XHTML generado es aprobado al 100%
  186. por el [ validador w3c http://validator.w3.org/].
  187. : **SGML**
  188. Es un formato de documento común que posee aplicaciones de conversiňn, como
  189. [sgmltools http://www.sgmltools.org]. A partir de un archivo SGML se pueden generar documentos html, pdf, info, latex, lynx, rtf y xml. Las herramientas como sgml2* también crean índices (TOC) automaticamente, dividiéndolos en secciones y subpáginas (sgml2html)
  190. Txt2tag genera archivos SGML válidos para DTD linuxdoc, listos para ser convertidos mediante una herramienta sgml2* sin archivo de catŕlogo extra u otras incomodas exigencias de SGML.
  191. : **LATEX**
  192. Es uno de los formatos de documento preferido en los medios académicos y es un formato más potente de lo que uno, de entrada, se imagina. Libros completos,fórmulas complicadas o cualquier texto complejo puede ser escrito en LaTeX. Pero si intentas escribir a mano las marcas requeridas, prepárate para la desesperación.
  193. Txt2tag genera archivos LaTeX listos para usar,realizando todo el complejo trabajo que requiere este formateo, con todas las excepciones. El escritor debe preocuparse sólo por el contenido.
  194. : **LOUT**
  195. Muy parecido a LaTeX, pero con una sintaxis mas fácil, utilizando "@" en lugar de "\" . Su proximidad a la idea de que "todo-es-objeto" da lugar a un marcado mas "sano".
  196. Txt2tag genera archivos Lout listos para su uso, que pueden ser convertidos a PS o PDF utilizando la orden "lout".
  197. : **MAN**
  198. Las páginas man de UNIX resisten el paso del tiempo. Los formatos de documentos vienen y van, pero ellas siguen aquí, inamovibles.
  199. Hay otras herramientas para generar páginas man, pero txt2tag tiene una ventaja: una fuente, múltiples formatos de destino. Así, el contenido de una misma página man puede ser convertido en una página HTML, una presentacion Magic Point, etc.
  200. : **MGP (Magic Point)**
  201. [Magic Point http://www.mew.org/mgp] es una herramienta de presentación bastante útil (tipo: Microsoft PowerPoint), que utiliza un lenguaje de marcado para definir todas las teclas. De esta forma puedes crear presentaciones complejas con vi/emacs/notepad.
  202. Txt2tag genera un archivo .mgp lísto para ser utilizado, definiendo todos los encabezamientos necesarios para las definiciones de fuentes y apariencia, así como el soporte a los carácteres acentuados (código ISO-8859).
  203. **Observación 1 :** los archivos .mgp creados por txt2tag usan las fuentes Type1 de Xfree86. De esta forma no es necesario incluir fuentes TrueType a su presentación.
  204. **Observación 2 ::** las definiciones de colores para las fuentes son límpias de forma que, incluso con una paleta de colores de sistema pobre, (cómo ``startx -- -bpp 8``),la presentación va a tener una buena apariencia.
  205. La clave es : Convierte y Usa. Sin necesidad de posteriores u otros requisitos.
  206. : **MOIN**
  207. ż No sabes lo que és [MoinMoin http://moin.sourceforge.net]?
  208. ĄEs un [WikiWiki http://www.c2.com/cgi/wiki]!
  209. La sintaxis de Moin es un poco liada: tienes que escribir cosas cómo
  210. ``{{{'''''adding braces and quotes'''''}}}``.Pero txt2tag viene con marcadores simplificados y una solución unificada: una fuente, múltiples formatos destino.
  211. : **PM6**
  212. żSabías que Adobe PageMaker 6.0 tiene su propio lenguaje de marcado?. Estilos, tablas de colores, modificadores de fuente y la mayor parte de las funcionalidades accesibles via 'clic' de ratón, también están disponibles en su lenguaje de marcado. Sólo tienes que acceder al menú "Import tagget text", aunque sea sólo por curiosidad, y podrás ver que es un lenguaje de marcas semejante al HTML.
  213. Txt2tag genera todas las marcas y define un encabezamiento extenso y funcional, configurando los estilos de párrafo y formatos.
  214. **ĄAtención!:** Sin saltos de linea. Cada párrafo debe ser una sola linea.
  215. Nota del Autor:
  216. //Todo mi libro sobre [expresiones regulares http://guia-er.sf.net]//
  217. //fue escrito con Vi, convertido al formato PageMaker con txt2tag//
  218. //y enviado a la imprenta.//
  219. : **TXT**
  220. TXT es texto. El único tipo de formato verdadero.
  221. A pesar que las marcas de txt2tag son intuitivas y discretas, puedes eliminarlas convirtiendo el archivo al formato TXT puro.
  222. Los títulos estaran subrayados y el texto es, basicamente, conservado cómo estaba en el archivo fuente.
  223. ------------------------------------------------------------------------
  224. == Estructuras Soportadas en los Archivos finales ==[struct-support]
  225. || Estructura | html | xhtml | sgml | tex | lout | man | mgp | moin | pm6 | txt |
  226. | cabeceras | S | S | S | S | S | S | S | N | N | S |
  227. | sección título | S | S | S | S | S | S | S | S | S | S |
  228. | párrafos | S | S | S | S | S | S | S | S | S | S |
  229. | negrita | S | S | S | S | S | S | S | S | S | - |
  230. | itálica | S | S | S | S | S | S | S | S | S | - |
  231. | subrayado | S | S | - | S | S | - | S | S | S | - |
  232. | f.monoespacio | S | S | S | S | S | - | S | S | S | - |
  233. | línea verbatim | S | S | S | S | S | S | S | S | S | - |
  234. | área verbatim | S | S | S | S | S | S | S | S | S | - |
  235. | área de cita | S | S | S | S | S | S | S | S | S | S |
  236. | links internet | S | S | S | - | - | - | - | S | - | - |
  237. | links e-mail | S | S | S | - | - | - | - | S | - | - |
  238. | links locales | S | S | S | N | N | - | - | S | - | - |
  239. | links nombrados | S | S | S | - | - | - | - | S | - | - |
  240. | listas marcadas | S | S | S | S | S | S | S | S | S | S |
  241. | listas numeradas | S | S | S | S | S | S | S | S | S | S |
  242. | listas definición | S | S | S | S | S | S | N | N | N | S |
  243. | línea horizontal | S | S | - | S | S | - | S | S | N | S |
  244. | imágen | S | S | S | S | S | - | S | S | N | - |
  245. | tabla | S | S | S | S | N | S | N | S | N | N |
  246. || Extras | html | xhtml | sgml | tex | lout | man | mgp | moin | pm6 | txt |
  247. | alineación imágen | S | S | N | N | Y | - | S | N | N | - |
  248. | alin celdas tb | S | S | S | S | N | Y | N | S | N | N |
  249. | span columna tb | S | S | N | N | N | N | N | N | N | N |
  250. || | Significados
  251. | **S** | //Soportado//
  252. | **N** | //No soportado (tal vez en futuras versiones....)//
  253. | **-** | //No soportado (no es posible en este tipo de archivo final)//
  254. % | **?** | //not supported (not sure if it can be done or not)//
  255. ------------------------------------------------------------------------
  256. == Las tres interfaces de usuario: GUI, Web y Línea de Comandos ==[interfaces]
  257. Considerando que distintos usuarios pueden tener distintas necesidades y/o disponer de entornos diversos, txt2tags flexibiliza su forma de utilización, presentándose en tres posibles interfaces de usuario, cada una de ellas con sus propias peculiaridades y funcionalidades.
  258. - **Gui**: Escrita en Tk. Aporta a txt2tags un entorno de ventanas y la facilidad del "clic" de ratón.
  259. - **Web**: Escrita en PHP, permite operar remotamente con txt2tags, mediante un navegador, sin necesidad de instalación local
  260. - **Línea de Comandos**: Escrita en Phyton, es el núcleo del programa. Todas las funcionalidades y opciones del programa son accesibles desde la Línea de Comandos.
  261. ------------------------------------------------------------------------
  262. === Interfaz Gráfica Tk ===[gui]
  263. Desde su versión 1.0, txt2tags dispone de una interfaz gráfica que funciona en Linux, Mac, Windows y otros sistemas operativos.
  264. Al invocar txt2tags (desde la línea de comandos), el programa detecta automaticamente si el sistema soporta la interfaz gráfica y, en caso afirmativo, la lanza sin necesidad de órdenes adicionales. Se puede forzar el lanzamiento de la interfaz gráfica mediante la opción --gui. Si se detectara la falta de algún componente para el funcionamiento de la interfaz gráfica, el programa nos lo advertirá.
  265. **Nota:** Se necesita el módulo Tkinter. Forma parte de la distribución estandar de Python. De tener instalado éste,deberia disponerse del citado módulo.
  266. La interfaz es simple e intuitiva:
  267. [IMGPATH/gui.png]
  268. + Localizar el archivo fuente .t2t en el disco.
  269. + Elegir un tipo de documento de salida.
  270. + A continuación podran elegirse una serie de opciones, aunque ninguna de ellas es imprescindible.
  271. + Finalmente, activando "Convert!", se realiza la conversión del documento.
  272. Una de las opciones cuya activación puede ser útil es "//Dump to screen//", (Visualización en pantalla), que nos permite ver el código generado en una ventana distinta a la de trabajo sin que, por el momento, se guarde ningún archivo. Si el código se considera correcto, desactivamos la opción y la conversión se realizará normalmente.
  273. Los colores que vienen por defecto pueden cambiarse en el archivo ``~/.txt2tagsrc``
  274. usando los ajustes ``%!guicolors`` Por ejemplo:
  275. ```
  276. % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
  277. %!guicolors: blue white brown yellow
  278. ```
  279. ------------------------------------------------------------------------
  280. === Interfaz Web ===
  281. La interfaz web se encuentra disponible en: http://txt2tags.org/online.php . Allí puedes usar y probar el programa sin necesidad de instalarlo localmente.
  282. [IMGPATH/web.png]
  283. También puede instalarse esta interfaz en la intranet local, evitando así tener que proceder a la instalación de txt2tags en cada una de las computadoras.
  284. ------------------------------------------------------------------------
  285. === Interfaz de Línea de Comandos (Cónsola) ===[cmdline]
  286. A los usuarios de esta interfaz, la opción --help les debe proporcionar salida en pantalla parecida a čsta:
  287. ```
  288. Usage: txt2tags [OPTIONS] [infile.t2t ...]
  289. -t, --target set target document type. currently supported:
  290. html, xhtml, sgml, tex, lout, man, mgp, moin, pm6, txt
  291. -i, --infile=FILE set FILE as the input file name ('-' for STDIN)
  292. -o, --outfile=FILE set FILE as the output file name ('-' for STDOUT)
  293. -n, --enum-title enumerate all title lines as 1, 1.1, 1.1.1, etc
  294. -H, --no-headers suppress header, title and footer contents
  295. --headers show header, title and footer contents (default ON)
  296. --encoding set target file encoding (utf-8, iso-8859-1, etc)
  297. --style=FILE use FILE as the document style (like HTML CSS)
  298. --css-sugar insert CSS-friendly tags for HTML and XHTML targets
  299. --css-inside insert CSS file contents inside HTML/XHTML headers
  300. --mask-email hide email from spam robots. x@y.z turns <x (a) y z>
  301. --toc add TOC (Table of Contents) to target document
  302. --toc-only print document TOC and exit
  303. --toc-level=N set maximum TOC level (depth) to N
  304. --rc read user config file ~/.txt2tagsrc (default ON)
  305. --gui invoke Graphical Tk Interface
  306. -q, --quiet quiet mode, suppress all output (except errors)
  307. -v, --verbose print informative messages during conversion
  308. -h, --help print this help information and exit
  309. -V, --version print program version and exit
  310. --dump-config print all the config found and exit
  311. Turn OFF options:
  312. --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
  313. --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
  314. --no-css-sugar, --no-css-inside, --no-quiet
  315. Example:
  316. txt2tags -t html --toc myfile.t2t
  317. By default, converted output is saved to 'infile.<target>'.
  318. Use --outfile to force an output file name.
  319. If input file is '-', reads from STDIN.
  320. If output file is '-', dumps output to STDOUT.
  321. ```
  322. ==== Ejemplos: ====
  323. Suponiendo que se haya creado un archivo marcado,denominado ``file.t2t``, veamos varias opciones de conversión:
  324. | **Convertir a HTML** | ``$ txt2tags -t html file.t2t``
  325. | **Usando redireccionamiento** | ``$ txt2tags -t html -o - file.t2t > file.html``
  326. | | .
  327. | **Con Índice de Contenidos** | ``$ txt2tags -t html --toc file.t2t``
  328. | **Con Títulos Numerados** | ``$ txt2tags -t html --toc --enum-title file.t2t``
  329. | | .
  330. | **Vista rápida del Índice** | ``$ txt2tags --toc-only file.t2t``
  331. | **żÍndice numerado? ĄSi!** | ``$ txt2tags --toc-only --enum-title file.t2t``
  332. | | .
  333. | **...... desde STDIN** | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -``
  334. | **Enmascarando los e-mails** | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -``
  335. | **Edición post-conversión** | ``$ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html``
  336. : //Nota//
  337. Desde la versión 1.6 es posible realizar un tratamiento pre y post conversión mediante los filtros
  338. ``%!preproc`` y ``%!postproc`` .
  339. ========================================================================
  340. = Parte II: - OK!, Quiero utilizar el programa. żQue debo hacer ? =[install]
  341. Sencillamente, descargar el programa y hacer que corra en tu máquina :-).Veamos como hacerlo.
  342. == Obtener e instalar Python ==[download-python]
  343. En primer lugar, deberemos instalar el interprete Python en nuestro sistema. Si ya lo tenemos instalado, podemos saltarnos este apartado.
  344. Python es uno de los mejores lenguajes de programación. Funciona en Linux, Mac, Windows y otros Sistemas Operativos. Puede descargarse del la web de [Python http://www.python.org]. Las instrucciones para su instalación se encuentran disponibles en este mismo site. Txt2tags funciona mejor con versiones de Python 1.5 o superiores.
  345. Si no estais seguros de tener Python instalado en vuestro sistema, abrid una consola ( tty, xterm, MSDOS..) y lanzad el comando ``python``. Si no está instalado, vuestro sistema os lo advertirá
  346. == Obtener Txt2tags ==[download-txt2tags]
  347. El sitio oficial de la distribución de txt2tags es: http://txt2tags.org/src .
  348. Todos los archivos son del tipo "tarball" (tar.gz,.tgz), que pueden ser descomprimidos por la mayoria de los programas de descompresión (incluido Winzip).
  349. Debemos procurar obtener la **última versión** (la mas reciente o el número de versión mas alto). Las versiones precedentes se conservan el el repositorio por razones puramente históricas.
  350. == Instalar txt2tags ==[install-txt2tags]
  351. Como todos los scripts Python, txt2tags apenas precisa de instalación.
  352. El único archivo necesario para el programa es el script txt2tags. Los demás archivos tar.gz (.tgz) son la documentación, las utilidades y los archivos de ejemplo.
  353. El medio mas seguro de iniciar txt2tags es "llamarlo" desde Python.
  354. ``` prompt$ python txt2tags
  355. Si deseais instalar txt2tags como programa en vuestro sistema, copiad (o cread un enlace) el script txt2tags en un directorio referenciado por la variable $PATH y aseguraos de que el sistema pueda lanzar el programa.
  356. : **UNIX/Linux**
  357. Asegurémosnos de que el script es ejecutable : ``chmod +x txt2tags`` y, seguidamente lo copiamos en un directorio referenciado por $PATH:
  358. ``cp txt2tags /usr/local/bin``
  359. : **Windows**
  360. Renombrar el script ańadiéndole la extensión .py :
  361. ``ren txt2tags txt2tags.py`` y copiarlo en un directorio referenciado en $PATH:
  362. ``copy txt2tags.py C:\WINNT``
  363. Después de esto, si deseais utilizar el entorno gráfico, podreis crear un icono en vuestro escritorio.
  364. === Paquetes especiales para los usuarios de Windows ===
  365. Existen dos distribuciones .EXE de txt2tags, que instalan el programa en maquinás Windows con solo unos cuantos "clics":
  366. - La primera es el simple script txt2tags para los que tengan instalado Python.
  367. - La segunda de estas dos distribuciones es la "versión completa", con la cuál no se precisa tener instalado Python en el sistema (Incluye una versión "ligera" de Python).
  368. Se pueden obnener en //Txt2tags-Win//: http://txt2tags-win.sf.net
  369. == Instalación de los Archivos de Sintaxis para los Editores de Texto ==[editor-syntax]
  370. Con txt2tags se proporcionan una serie de archivos de sintaxis prácticos, utilizables con los siguientes editores:
  371. - Vim (www.vim.org)
  372. - Emacs (www.emacs.org)
  373. - Nano (www.nano-editor.org)
  374. - Kate (http://kate.kde.org)
  375. Estos archivos sintácticos contienen todas las reglas y marcas que utiliza txt2tags, ayudándo al usuario a escribir los documentos sintacticamente correctos. Las marcas se visualizan en color, así podremos darnos cuenta de si escribimos correctamente.
  376. | [IMGPATH/vim.png] |
  377. | Ejemplo de archivo editado en Vim
  378. Cada editor tiene un procedimiento de instalación específico. Consulta el encabezamiento del archivo de sintaxis y la documentación del editor.
  379. ========================================================================
  380. = Parte III - Escribiendo y convirtiendo vuestro primer documento. =[your-1st-doc]
  381. == Probar las herramientas ==
  382. Para poder hacer vuestra primera conversión necesitareis tres cosas: txt2tags, un editor y un navegador web.
  383. + Comprobad que txt2tags funciona correctamente en vuestra máquina.
  384. - **Interfaz de Línea de Comandos:** Lanzad el comando txt2tags desde la línea de comandos. Deberá generarse una salida con un mensage similar a "Missing input file". Si no ocurre eso, probad con: "pyton /ruta/hacia/txt2tags" o con: "/ruta/hacia/python /ruta/hacia/txt2tags" en el caso de que python no esté en vuestro PATH.
  385. - **Interfaz GUI:** Si lanzamos txt2tags desde la línea de comandos, se iniciará con el sistema gráfico. En el caso de que hayamos creado un icono en el escritorio, "clicar" en el.
  386. + Abrid un editor de texto que conozcais bién, puede ser cualquiera, desde Vim a MSWord u Openoffice. Cread un nuevo documento, que será vuestro primer documento txt2tags.
  387. + Lanzad vuestro browser preferido para poder ver los resultados de la conversión en una pagina HTML.
  388. ------------------------------------------------------------------------
  389. == Escribir el encabezamiento del documento ==
  390. + Id al editor de texto y teclead una primera línea , por ejemplo: //Mi Primer Documento//
  391. + En una segunda línea teclead un sub-título, por ejemplo://txt2tags//
  392. + Después, en una tercera línea teclead, por ejemplo, una fecha: //Domingo 17 Julio 2005//
  393. Así, dispondremos de un documento con el siguiente contenido:
  394. ```
  395. Mi primer documento
  396. txt2tags
  397. Domingo 17 Julio 2005
  398. ```
  399. Aunque ésto sea sólo una parte del documento, podemos convertirlo y comprobar el resultado.
  400. Guardad el documento con el nombre ``test.txt`` en un directorio desde donde, más tarde, podamos recuperarlo (en los siguientes ejemplos el documento se ha guardado en el directorio /tmp).
  401. ------------------------------------------------------------------------
  402. == La Primera Conversión : La Interfaz Gráfica. ==
  403. Si utilizais la interfaz de línea de comandos, pasad a la siguiente sección.
  404. Si utilizais la interfaz gráfica, proceded tal como a continuación se indica:
  405. [IMGPATH/firstdoc.png]
  406. + Clicar en el botón "Browser", navegad hasta el directorio en el que guardasteis el documento test.tx y seleccionarlo.
  407. + En el apartado "Choose the target document type" (Elija el tipo de documento de salida) escoged : "HTML page"
  408. + Clicar el boton "Convert!" (Convertir)
  409. [IMGPATH/firstdoc-done.png]
  410. Aparecerá un diálogo que nos informa que la conversión se ha realizado con éxito. Notad que el archivo HTML generado ha sido guardado en el mismo directorio que el archivo test.txt, pero con la extensión .html
  411. ------------------------------------------------------------------------
  412. == La Primera Conversión: Interface en Línea de Comandos ==
  413. Si utilizais la interfaz gráfica, id a la sección anterior.
  414. Si utilizais la interfaz de Línea de Comandos, id al directorio en el que está guardado test.txt y teclead el siguiente comando:
  415. ``` txt2tags --target html test.txt
  416. Observad que hay un espacio en blanco entre cada una de las partes del comando, pero no en --target. Dicha opción es seguida por html, que indica al programa el formato al que deseamos convertir el archivo de texto. La última parte de la orden es el nombre del archivo de texto que deseamos convertir.
  417. Si la conversión se realiza con éxito, el resultado es guardado como ``test.html``
  418. y el programa nos dará un mensaje del tipo: "//txt2tags wrote test.html//" . En caso contrario ,os indicará el error cometido. Verificadlo con atención.
  419. Esto es una muestra de lo que podeis ver en la pantalla:
  420. ```
  421. prompt$ txt2tags --target html test.txt
  422. txt2tags wrote test.html
  423. prompt$
  424. ```
  425. ------------------------------------------------------------------------
  426. == Comprobar el resultado ==
  427. Abrir el archivo ``test.html`` con el navegador y comprobar el resultado de la conversiňn.
  428. [IMGPATH/firstdoc-html.png]
  429. Ą Bién ! Os habeis limitado a teclear tres simples líneas de texto y txt2tags ha realizado todo el trabajo necesario para configurar el encabezamiento de la pagina HTML. El alineamiento del texto, los márgenes, los espaciados, la apariencia, etc. Podemos observar como el título principal del documento aparece también en el borde superior del navegador (o en el título de la pestańa, en el caso de que usemos uno que aporte esta función).
  430. || Vosotros escribis el texto, txt2tags hace el resto :-) |
  431. Truco: podeis utilizar CSS en las páginas HTML generadas por txt2tags. De esta forma la apariencia de la página es configurable al 100%.
  432. ------------------------------------------------------------------------
  433. == Escribir el cuerpo del documento ==
  434. Volvamos al editor de texto, ya que la siguiente etapa consistirá en escribir el cuerpo del documento. Podeis escribirlo en texto plano, el mismo que usais en los e-mail. Podreis observar como txt2tags reconoce automaticamente los párrafos y las listas de elementos, sin necesidad de "marcarlos".
  435. Guardad de nuevo el documento y proceded a su conversión, tal como se indicó en la anterior sección. Comprobad el resultado. Éste es el ciclo de desarrollo de documentos con txt2tags. No necesitais más que centraros en el contenido del documento, obteniendo el documento final mas rápidamente que con otros editores. Sin interminables "clics" de ratón, ni menús, ni ventanas ni distracciones.
  436. Observad el contenido del archivo de texto plano ``test.txt`` y comparémoslo con el archivo HTML generado:
  437. ```
  438. Mi primer documento
  439. txt2tags
  440. Domingo 17 Julio 2005
  441. Bueno, vamos a probar txt2tags.
  442. No se me ocurre nada que escribir. Probemos con una lista.
  443. Necesitaria:
  444. - Ducharme
  445. - Comer una pizza
  446. - Dormir
  447. ```
  448. [IMGPATH/firstdoc-fullhtml.png]
  449. Con txt2tags es posible escribir una página web entera sin ningún conocimiento de HTML. No necesitareis intertar ninguna marca. Además, el mismo archivo de texto plano puede convertirse en cada uno de los demás formatos soportados por txt2tags.
  450. Además del texto plano, txt2tags proporciona una serie de marcas muy simples que pueden utilizarse cuando se tenga necesidad de otros formatos o estructuras, como puede ser el texto en negrita, cursiva o itálica, los títulos, las imágenes, las tablas y otros. Un ejemplo rapido:
  451. ``**comienza en negrita**`` y ``== los signos igual para el título ==``.
  452. Para aprender a utilizar estas marcas consultad el archivo [Txt2tags Markup Demo http://txt2tags.org/markup.html].
  453. =======================================================================
  454. = Parte IV - Dominando los Conceptos de Txt2tags =[concepts]
  455. == Las Áreas de un Documento .t2t ==[areas]
  456. Los archivos marcados por txt2tags se dividen en 3 áreas. Cada una de estas tres áreas tiene sus propias reglas y finalidades. Estas áreas son:
  457. : //ENCABEZAMIENTO//
  458. Lugar para el título del documento, nombre del autor, versión y fecha. (opcional)
  459. : //CONFIGURACIÓN//
  460. Lugar para la configuración general del documento. (opcional)
  461. : //CUERPO//
  462. Lugar en el que se coloca el contenido del documento. (obligatoria)
  463. Como se ha podido observar, solo el área del //CUERPO//
  464. es obligaroria.
  465. Cada área esta regulada por reglas específicas, que se detallarán en el siguiente capítulo. Por ahora, vamos a quedarnos con una representación gráfica de las áreas de un documento txt2tags:
  466. ```
  467. _________________
  468. | |
  469. | ENCABEZAMIENTO | 1. En primer lugar,los Encabezamientos
  470. | |
  471. | CONFIGURACIÓN | 2. Después,las Configuraciones
  472. | |
  473. | CUERPO | 3. Finalmente,el Cuerpo del documento,
  474. | |
  475. | ... | el cual abarca hasta el final
  476. | ... |
  477. |_________________|
  478. ```
  479. En resumen, así es como se definen las tres áreas:
  480. | **Encabezamiento** | Las primeras 3 líneas del archivo. O la primera línea en blanco, cuando no se quiere un Encabezamiento.
  481. | **Configuración** | Desde la 4Ş linea (o desde la 2Ş , en el caso que no se contemple Encabezamiento) hasta donde comience el Cuerpo del Documento..
  482. | **Cuerpo** | Comienza con la primera línea de texto válido (no "comentado" o que no sea una configuración) después del Encabezamiento.
  483. === Veamos un ejemplo: ===
  484. ```
  485. My nice doc Title
  486. Mr. John Doe
  487. Last Updated: %%mtime(%c)
  488. %! Target : html
  489. %! Style : fancy.css
  490. %! Encoding: iso-8859-1
  491. %! Options : --toc --enum-title
  492. Hi! This is my test document.
  493. Its content will end here.
  494. ```
  495. ------------------------------------------------------------------------
  496. == Área de Encabezamiento ==[headers-area]
  497. Localización:
  498. - Posicion fija: Las **tres pimeras líneas** de un archivo. Eso es todo :-)
  499. - Posicion fija: La **primera línea** de un archivo, si se trata de una línea en blanco. Esto signfica "Encabezamiento vacio".
  500. El Área de Encabezamiento es la única que tiene una posición fija, determinada por líneas. Se encuentra siempre en las tres primeras líneas del archivo fuente.
  501. El contenido de estas líneas no esta regulado, es libre, aunque se recomienda que se siga la siguiente pauta:
  502. - //línea 1//: título del documento
  503. - //línea 2//: nombre del autor y/o email
  504. - //línea 3//: fecha del documento y/o versión (un buén lugar para ``%%date``)
  505. Retengamos que las tres primeras líneas del documento fuente serán las tres primeras líneas del documento final, separadas y diferenciadas del resto del contenido del documento ( p.e.,carácteres mas grandes, en negrita). Si es posible la paginación, encontraremos el encabezamiento sólo y centrado en la primera página.
  506. ==== Menos (o Ninguna) líneas de Encabezamiento ====
  507. Tal vez deseemos menos líneas de encabezamiento. Por ejemplo, solo deseamos especificar el título y la fecha.
  508. Para ello bastara con dejar la 2Ş y/o la 3Ş línea en blanco. Esta/s líneas en blanco no serán incluidas en el documento final. Pero no debemos olvidar que, aún en blanco, estas líneas forman parte del Área de Encabezamiento del documento y que el Cuerpo del mismo comenzará **a partir de** la tercera línea.
  509. La primera línea (normalmente, el título) es la unica línea requerida en el Área de Encabezamiento. Recordemos que la primera línea en blanco indica **Encabezamiento vacio**, lo que origina que el //Área de Encabezamiento// se inicie a partir de la 2Ş línea.
  510. No configurar un encabezamiento puede sernos de utilidad en el caso de querer insertar un encabezamiento personalizado después de la conversión. Para éste tipo de operación generalmente se requiere la opción de línea de comandos ``--no-headers``.
  511. %==== Straight to the point ====
  512. || En resumen: Los Encabezamientos son posiciones, no contenidos. |
  513. Si colocamos un texto en la primera línea del archivo fuente, aparecerá en la primera línea del documento convertido. Lo mismo para las 2Ş y 3Ş líneas.
  514. ------------------------------------------------------------------------
  515. == Area de Configuración ==[config-area]
  516. Localización:
  517. - Comienza justo despues del Área de Encabezamiento
  518. - Comienza a partir de la 4Ş línea si se especifican encabezamientos
  519. - Comienza a partir de la 2Ş línea en el caso de **Encabezamiento vacio**.
  520. - Finaliza donde comienza el Área del Cuerpo del documento
  521. - Finaliza en una línea en blanco, en una línea que sea un comentario o en una línea que no sea de ajuste/configuración.
  522. El Área de Configuración es opcional. Cualquiera puede generar documentos txt2tags sin siquiera conocer la existencia de dicha área, pero el usuario experimentado dificilmente podra prescindir de la ventaja y el control que dicha área le proporcionará.
  523. El Área de Configuración nos servirá para definir en ella configuraciones que afecten al comportamiento del programa, evitando asi tener que escribir dichas opciones en la línea de comandos en el momento de ralizar la conversión.
  524. Para mas información, consultar la Sección:[Configuraciones (Settings section) #settings-overview].
  525. ----------------------------------------------------------------
  526. == Área del Cuerpo del Documento ==[body-area]
  527. Localización:
  528. - Comienza con la primera línea válida de texto del archivo.
  529. - Las líneas que contienen ajustes o comentarios y las líneas en blanco no se consideran líneas válidas de texto
  530. - Finaliza al final del archivo (EOF)
  531. Consideraremos Cuerpo todo lo que no sea ni Encabezamiento ni Configuración.
  532. El Cuerpo está constituido por el contenido del documento y todas aquellas estructuras y formatos que txt2tags puede reconocer.
  533. En el Cuerpo pueden incluirse comentarios para los //TODOs// y notas personales.
  534. Puede utilizarse la opción en línea de comandos ``--no-headers`` para convertir solo el Cuerpo del documento, suprimiendo los Encabezamientos. Esto es práctico cuando se tienen Encabezamientos personalizados en un archivos aparte, que se concatenará seguidamente con el documento que estemos procesando.
  535. ----------------------------------------------------------------
  536. == Configuraciones: żCómo Configurar algo?. żCuál es la sintaxis? ==[settings-overview]
  537. Las líneas de configuración son líneas de comentario especiales, situadas en el Área de Configuración, que afectan al proceso de conversión. Su sintaxis, tan simple como la atribución de valor a una variable, está compuesta por una palabra-clave y un valor, separados la una del otro por el separador canonico dos-puntos **":"** . Su sintaxis es:
  538. || %! palabra-clave : valor |
  539. Lista de claves válidas:
  540. || Clave | Descripción |
  541. | Target | Define el formato al cuál debe ser convertido el documento.
  542. | Options | Es útil para especificar las opciones de línea de comando para el archivo fuente. El formato de las opciones es el mismo que el utilizado en la línea de comandos. Usando esta opción junto con %!target permite convertir el documento simplemente con la orden: txt2tags file.t2t
  543. | Style | Sólo es soprtado por el documento destino HTML, para definir una hoja de estilo (CSS)
  544. | Encoding | Es una configuración importante en documentos que contienen acentos y carácteres no ASCII, ya que permite personalizar el Conjunto de Carácteres (Codificación de Carácteres).
  545. | PreProc | Es un filtro. Define reglas del tipo "busca y sustituye" que serán aplicadas al archivo original antes de cualquier análisis por parte de txt2tags.
  546. | PostProc | Es un filtro. Define reglas del tipo "busca y sustituye" que serán aplicadas al archivo destino después de todo el procesamiento por parte de txt2tags.
  547. Ejemplo:
  548. ```
  549. %! Target : html
  550. %! Options : --toc --toc-level 3
  551. %! Style : fancy.css
  552. %! Encoding: iso-8859-1
  553. %! PreProc : "AMJ" "Aurelio Marinho Jargas"
  554. %! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">'
  555. ```
  556. -----------------------------------------------------------------------
  557. === Algunas reglas sobre las Configuraciones ===
  558. - Las configuraciones son válidas solo dentro del Area de Configuración. Serán tratadas como comentarios simples si se encuentran en el Cuerpo del documento.
  559. - Si la misma palabra-clave aparece más de una vez en el Area de Configuración, solo se utilizara la última. Excepciones: Options, PreProc y PostProc, que son acumulativas.
  560. - Una línea de configuración con una palabra-clave inválida será considerada un comentario.
  561. - Las opciones de configuración situadas en el Área de Configuración tienen preferencia dentro del archivo txt2tags, pero no sobre las opciones en Línea de Comando.
  562. == Opciones en Línea de Comando ==[options]
  563. El modo más rápido de cambiar el comportamiento por defecto es utilizando las opciones de la línea de comando. Esto es sólo posible cuando se utiliza la citada interfaz, no cuando se utilizan las interfaces Web o GUI.
  564. El programa acepta un juego de opciones predefinidas. Una opción es un guión ("-") seguido de una letra o dos guiones ("--") seguidos de una o mas palabras, como ``-t`` y ``--target``.
  565. A propósito de la opción "target": resulta ser la única opción obligatoria. Todas las demás opciones son eso, opcionales. :-)
  566. Las opciones más utilizadas son ``--outfile`` para activar la generación automática de índices de materias y
  567. ``--encoding`` que nos permite escoger el tipo de codificación de caracteres. La mayoria de las opciones pueden ser desactivadas precediéndolas de "no-" , por ejemplo:
  568. ``--no-encoding`` and ``--no-toc``.
  569. Pueden configurarse las opciones que se deseen utilizar en un determinado archivo origen, en el Ärea de Configuración del mismo archivo, mediante la regla de configuración ``%!options`` . Esto nos evita el tecleado de las opciones en la línea de comando.
  570. Por ejemplo: ``%!options: --toc -o mydoc.html``.
  571. La excepción es la especificacion del formato del archivo final, que tiene su propia sintaxis: ``%!target: html``.
  572. La opción ``--help`` nos proporcionará una lista completa de las opciones disponibles.
  573. -----------------------------------------------------------------------
  574. == Archivo de Configuracion del Usuario (RC) ==[rc]
  575. El archivo de configuración del usuario (llamado también archivo RC) es el lugar donde se guardan las reglas de las configuraciones que pueden ser compartidas por TODOS los archivos. Si utilizas las mismas reglas de configuración en todos los archivos .t2t que escribais, incluidlas en el archivo RC y podrán ser utilizadas globalmente, tanto por los existentes como por futuros archivos fuente.
  576. El emplazamiento por defecto de este archivo depende del sistema que se esté utilizando. De todas maneras, dicho emplazamiento puede ser modificado por el usuario utilizando una variable de entorno.
  577. || | RC file location |
  578. | Windows: | ``%HOMEPATH%\_t2trc``
  579. | Linux y otros: | ``$HOME/.txt2tagsrc``
  580. | Definidod por usuario: | ``T2TCONFIG`` env var
  581. El formato de las reglas de configuración es exactamente el mismo que el utilizado en el Área de Configuración de los archivos .t2t. Podemos encontrar un ejemplo de archivo RC en el "tarball"
  582. ``doc/txt2tagsrc``
  583. Ejemplo:
  584. ```
  585. % my configs
  586. %%% Always use CSS-friendly tags in HTML
  587. %!options(html): --css-sugar
  588. %%% Change the default TOC depth for all targets
  589. %!options: --toc-level 4
  590. %%% Set the default encoding for all documents
  591. %!options: --encoding iso-8859-1
  592. ```
  593. Toda línea no vacia, un comentario o una línea de configuración vŕlida puede generar un error durante la ejecución de txt2tags. Sed muy cautelosos a la hora de editar el archivo RC.
  594. Txt2tags aplica automaticamente el archivo RC a todo archivo fuente que convierta. Si se desea desactivar el comportamiento para un determinado archivo, utilizad la opción ``--no-rc``.
  595. == Orden de Aplicación de las Configuraciones y Precedencia ==[config-loading]
  596. Hay tres formas de indicar a txt2tags cuales opciones y configuraciones utilizar y el orden que debe aplicarlas:
  597. + El archivo de usuario RC ( .txt2tagsrc)
  598. + Una Área de Configuración en el documento fuente
  599. + Las opciones de línea de comando
  600. En primer lugar, el programa lee las configuraciones del archivo RC. Si no encuentra otras, las aplica. Si encuentra configuraciones en el Área de Configuración del documento fuente, las lee, sobrescribiendo las configuraciones de RC. Finalmente, si encuentra opciones en la línea de comando,las lee, sobreescribiento a cualquiera de las otras dos anteriones.
  601. Asi, si el "encoding" del documento fuera definido en las tres opciones, se aplicarian las opciones definidas en la linea de comando.
  602. -----------------------------------------------------------------------
  603. == El Comando %!include ==[include]
  604. Desde la versión 1.7, es posible la utilización del comando ``include`` para insertar el contenido de un archivo externo en el Cuerpo del documento original.
  605. ``include`` es un comando, no una configuración. Es solo válido cuando se incluye en el //Área del Cuerpo del documento//.
  606. ``include`` es útil para dividir un documento grande en varios archivos menores ( p.e. en capítulos) o para incluir todo el contenido de un archivo externo cualquiera en el documento fuente.
  607. Ejemplo:
  608. ```
  609. My first book
  610. Dr. John Doe
  611. 1st Edition
  612. %!include: intro.t2t
  613. %!include: chapter1.t2t
  614. %!include: chapter2.t2t
  615. ...
  616. %!include: chapter9.t2t
  617. %!include: ending.t2t
  618. ```
  619. Como puede verse, basta con indicar el nombre del archivo después del comando ``include``. Las especificaciones opcionales del archivo final tambien són soportadas por el comando:
  620. ``` %!include(html): file.t2t
  621. Debemos tener presente que ``include`` insertará en el Área del Cuerpo el archivo .t2t, ignorando su encabezamiento y sus configuraciones. Esto nos permitirá convertir el documento incluido, separada o conjuntamente con el documento principal.
  622. Podemos considerar tres variantes de inclusión:
  623. - Verbatim
  624. - Raw
  625. - Tagged
  626. **Verbatim** : El texto es incluido preservando sus espacios y formato original, como si estuviese marcado por VERB. Para incluir un archivo de esta manera, basta con incluir su nombre entre (```):
  627. ``` %!include: ``/etc/fstab``
  628. **Raw** : El texto es incluido "como esta". No busca las marcas txt2tags, ni las interpreta. Es como si el texto estuviese entre marcadores (" ") de área protegida.
  629. Para incluir un archivo de esta menera basta con colocar su nombre entre dobles-comillas (" " ):
  630. ``` %!include: ""boom_text.txt""
  631. **Tagged** : El texto es pasado directamente al documento resultante, sin ningún tratamiento por parte de txt2tags. Mediante este procedimiento podemos incluir en el documento final textos marcados o con estructuras complejas no soportadas por txt2tags. Otra aplicación seria la de incluir un encabezamiento o un pié de página en todos los documentos. Para aplicar esta variante de inclusión debemos encerrar el nombre del archivo entre dobles-simples-comillas ( '' '' ) no entre dobles-comillas ("") como en el anterior caso.
  632. ``` %!include(html): ''footer.html''
  633. Como el contenido de cabecera.html contiene tags, es conveniente especificar el destino (html) para evitar problemas..
  634. -----------------------------------------------------------------------
  635. == El Comando %!includeconf ==[includeconf]
  636. ``includeconf`` se utiliza para incluir la configuración de un archivo externo en el archivo corriente. Es sólo válido cuando se incluye en el Área de Configuración.
  637. Es práctico cuando se desea tener la misma configuración para múltiples archivos, permitiéndonos centralizar su gestión. En el archivo en el que se quiera incluir la configuración global, incluir una llamada ``includeconf``.
  638. Ejemplo:
  639. ```
  640. Mi Primer Documento
  641. txt2tags
  642. Domingo 17 Julio 2005
  643. %!includeconf: config.t2t
  644. Este es un ejemplo de includeconf
  645. ```
  646. El formato del archivo incluido es el mismo que en el [archivo RC #rc].
  647. =======================================================================
  648. = Part V - Dominando las Marcas =[marks]
  649. Resúmen de las Marcas:
  650. || Básicas | ``...............`` | Modificadores | ``...............`` |
  651. | //Encabezamiento// | primeras 3 lineas | //Negrita// | ""**palabras**""
  652. | //Título// | = palabras = | //Itálica// | ""//palabras//""
  653. | //Título numerado// | + palabras + | //Subrayado// | ""__palabras__""
  654. | //Párrafo// | palabras | //Monospaciado// | ""``palabras``""
  655. || Bloque de Texto | ``...............`` | Otras | ``...............`` |
  656. | //Cita// | <TAB>palabras | //Línea de separación// | ------------...
  657. | //Lista// | - palabras | //Línea gruesa// | ============...
  658. | //Lista numerada// | + palabras | //Enlace// | ""[etiqueta url]""
  659. | //Lista definición// | : palabras | //Imágen// | ""[filename.jpg]""
  660. | //Línea Verbatim// | ``` palabras | //Comentario// | % comentarios
  661. | //Zona Verbatim// | ""```\n lineas \n```"" | //Texto Raw// | """"palabras""""
  662. | //Línea Raw// | """"""" palabras | //Tabla// | ""| celda1 | celda2 | celda3...""
  663. | //Zona Raw// | """""""\n lineas \n""""""" | //Ancla// | = titulo =[ancla]
  664. Reglas Generales:
  665. - **Encabezamiento:** son las tres primeras líneas del documento, las marcas no son intrepretadas.
  666. - **Titulos:** son carácteres "=" or "+" , equilibrados alrrededor del texto del título. A mayor número de carácteres, mayor "profundidad" de título ( titulo, sub-título, sub-sub-título, etc).
  667. - **Modificadores de Fuentes:** no aceptan espacios entre las marcas y su contenido.
  668. - **Comentario:** la marca "%" debe situarse al comienzo de la línea (primera columna).
  669. - **Imáges:** el nombre del archivo de imágen debe acabar en GIF, JPG, PNG o similar.
  670. - Las únicas marcas **multilinea** son las de las zonas verbatin y raw.
  671. - En las zonas verbatim y raw, ninguna marca es **interpretada**.
  672. - las **Líneas de Separación/Líneas Gruesas** deben tener, al menos, 20 carácteres.
  673. - El **(des) anidamiento** de las Citas y Listas viene determinado por la indentación.
  674. - La **fila de encabezamiento de una Tabla** se define con dos barras verticales || al principio de la fila.
  675. ------------------------------------------------------------------------
  676. %- MARKPROP Multiline, FreeSpaces, Align, Nesting
  677. %- MARKCONT Macros, Beautifiers, Quote, Lists, Table, Verbatim, Raw, Bars, Links, Image, Comment
  678. %-----------------------------------------------------------------------
  679. == Encabezamiento ==[mark-headers]
  680. - **Descripción:** Identifica las cabeceras del documento.
  681. - **Propiedades:** Multilinea, FreeSpaces, !Align, !Nesting
  682. - **Contiene:** Macros
  683. - **Sintaxis:**
  684. - Las tres primeras líneas del documento fuente.
  685. - Para no especificar encabezamiento, dejar la pimera línea blanco
  686. - Dejar en blanco la segunda y/o tercera línea para eliminar otras partes del encabezamiento.
  687. - **Detalles:**
  688. - Las marcas no son interpretadas.
  689. - Las tres primeras líneas del documento origen serán las tres primeras del documento final en el que aparecerá resaltadas. Si la paginación es soportada, pueden aparecer aisladas en la primera página del documento final.
  690. - El contenido del encabezamiento puede ser cualquier cosa, sin requisito alguno de formato. De todas formas, se recomienda seguir la siguiente estructura:
  691. - Linea 1: Título del documento
  692. - Linea 2: Nombre del autor y/o e-mail
  693. - Linea 3: Fecha del documento y/o versiňn ( buen lugar para ""%%mtime"")
  694. ------------------------------------------------------------------------
  695. == Título y Título Numerado ==[mark-title]
  696. - **Descripción:** Identifica un título de sección, numerado o no.
  697. - **Propiedades:**!Multiline, FreeSpaces, !Align, !Nesting
  698. - **Contenido:** Raw
  699. - **Sintaxis:**
  700. - Para títulos numerados, sustituir "=" por "+" en las siguientes reglas.
  701. - Equilibrio de signos alrededor de las palabras : ``= asi, si =`` ``==así, no =``
  702. - Mas signos,mas sub-niveles : ``=título=`` ``==subtítulo==`` ``===sub-subtitulo===``
  703. - Hay un máximo de 5 niveles ``====como esto====``
  704. - Los signos no equilibrados no dan lugar a un título : ``=no es tětulo===``
  705. - Se autorizan espacios dentro las marcas: ``= como esto =``
  706. - Los títulos pueden tener anclas: ``=título=[ancla]``. Para crear un ancla, crear un ``[enlace local#ancla]``
  707. - **Detalles:**
  708. - Las marcas no son interpretadas.
  709. - Las macros no son interpretadas.
  710. ------------------------------------------------------------------------
  711. == Párrafo ==[mark-paragraph]
  712. - **Descripción:** Identifica un párrafo de texto
  713. - **Propiedades:**Multiline, FreeSpaces, !Align, !Nesting
  714. - **Contenido:**Macros, Modificadores de Fuentes, Raw, Enlaces, Imagenes, Comentarios
  715. - **Sintaxis:**
  716. - Los párrafos son grupos de líneas delimitados por líneas vacias.
  717. - Otros bloques como las listas, las citas, las tablas y las zonas verbatim también cierran párrafos.
  718. ------------------------------------------------------------------------
  719. == Comentario ==[mark-comment]
  720. - **Descripción:** Usados para insertar un texto que no formará parte del documento final.
  721. - **Propiedades:** !Multiline, !<FreeSpaces, !Align, !Nesting
  722. - **Contenido:** --
  723. - **Sintaxis:**
  724. - Una línea con un caracter "%" en la primera columna: ``% como ésto``.
  725. - Sin espacio delante
  726. - **Detalles:**
  727. - Como comentarios, no se muestran en el texto convertido.
  728. - No son un bloque: cada línea de comentario debe comenzar con "%"
  729. - Útiles para TODOs,llamadas FIXME y notas del editor
  730. ------------------------------------------------------------------------
  731. == Modificadores de Fuentes: Negrita, Itálica y Subrayado ==[mark-beautifiers]
  732. - **Descripción:** Utilizado para insertar texto en negrita/itálica/subrayado,en un párrafo, una tabla, una lista o una cita
  733. - **Propiedades:**!Multiline, !FreeSpaces, !Align, Nesting
  734. - **Contenidos:** Macros, Modificadores de Fuentes, Raw, Enlaces, Imágenes
  735. - **Sintaxis:**
  736. - Dos arteriscos alrrededor para la negrita: ``**como ésto**``
  737. - Dos barras alrededor para la itálica: ``//como ésto//``
  738. - Dos guiones-bajos alrededor para el subrayado: ``__como ésto__``
  739. - No debe haber espacio entra las marcas y el contenido: ``** esto és inválido **``
  740. - **Detalles:**
  741. - Todos los modificadores de fuentes deben estar sobre una misma línea del archivo original, no debe haber un salto de línea
  742. - Las macros deben emplazarse en el interior de los modificadores de fuentes: ``**%%date**``
  743. - Pueden anidarse : ``**__como__//aqui//**``
  744. ------------------------------------------------------------------------
  745. == Fuente no Proporcional (Monoespaciada) ==[mark-monospaced]
  746. - **Descripción:** Utilizado para insertar un texto en fuente no proporcional en un párrafo, una tabla o una cita
  747. - **Propiedades:** !Multiline, !FreeSpaces, !Align, !Nesting
  748. - **Contenido:** --
  749. - **Sintaxis:**
  750. - Dos apóstrofes inversos: ````como aqui````
  751. - No debe haber espacio entre las marcas y el contenido: ```` esto és inválido ````
  752. - **Detalles:**
  753. - Las marcas no son interpretadas
  754. - Las macros no son interpretadas
  755. - Todo el texto en fuente no proporcional debe estar en una sóla línea del archivo fuente, no se admiten saltos de línea
  756. - En algunos archivos convertidos, los espacios internos son mantenidos, en otros, los espacios múltiples son reemplazados por espacios sencillos
  757. - Se puede crear un texto en negrita en fuente no proporcional insertándolo en las marcas de negrita : ``""**``negrita``**""``. Lo mismo para los otros dos modificadores, itálica y subrayado: ``""//``italica``//""`` y ``""__``subrayado``__""``
  758. ---------------------------------------------------------------------
  759. == Línea Verbatim, Zona Verbatim ==[mark-verbatim]
  760. - **Descripción: **Usado para insertar código-programa u otro texto pre-formateado en un párrafo, tabla, lista o cita, preservando los espacios, los saltos de línea y usando fuente no proporcional (monoespaciada)
  761. - **Propiedades:**Multiline, !FreeSpaces, !Align, !Nesting
  762. - **Contenido:** --
  763. - **Sintaxis: Línea Verbatim:**
  764. - Una línea que comienza exactamente con 3 apóstrofes inversos, seguidos de un espacio y seguido de texto: ``""```"" como ésto``
  765. - Los apóstrofes inversos deben estar en la primera columna, sin espacios delante
  766. - **Sintaxis: Zona Verbatim:**
  767. - Una línea que comienza exactamente con 3 apóstrofes inversos ``````` seguidos de líneas de texto, seguidas de otra línea con exactamente 3 apóstrofes inversos ```````.
  768. - No está permitido ningun espacio antes y después de las marcas
  769. - **Detalles:**
  770. - Las marcas no son interpretadas
  771. - Las macros no son interpretadas
  772. - Si se activa el fin del archivo (EOF), la zona verbatim acaba
  773. ---------------------------------------------------------------------
  774. == Línea de Separación , Línea Gruesa ==[mark-separator]
  775. - **Descripción:** Identifica una línea de separación o una línea gruesa.
  776. - **Propiedades:** !Multiline, FreeSpaces, !Align, !Nesting
  777. - **Contenido:** --
  778. - **Sintaxis:**
  779. - La línea de separación puede estar compuesta por guiones "-" o de carácteres de subrayado "_"
  780. - La línea gruesa está compuesta por signos igual "="
  781. - Deben usarse, al menos, 20 signos "-", "_" o "="
  782. - Tanto al principio como al final de la línea pueden colocarse espacios
  783. - Cualquier otro carácter colocado sobre la línea invalida la marca
  784. - **Detalles:**
  785. - Si el archivo final no admite línea de separación, ésta es reemplazada por un comentario
  786. - La línea gruesa puede tener distintos aspectos en ciertos tipos de archivos finales:
  787. - Una línea de separación más gruesa
  788. - Una pausa, en los formatos de presentación del tipo MagicPoint
  789. - Un salto de página, en formatos con paginación, del tipo LaTeX
  790. ---------------------------------------------------------------------
  791. == Enlaces, Enlaces nombrados ==[mark-link]
  792. - **Descripción:** Identifica un enlace remoto (internet) o local
  793. - **Propiedades:**!Multiline, !FreeSpaces, !Align, !Nesting
  794. - **Contenido:** Macros, Raw, Imágenes
  795. - **Sintaxis:**
  796. - Cualquier dirección internet válida ( URL, Ftp, news, e-mail) es detectada y convertida automaticamente
  797. - La indicación del protocolo ( http, https, ftp) es opcional : ``www.comoesto.net``
  798. - Puede utilizarse un nombre para un enlace: ``[clicar aqui www.url.net]``
  799. - Una imágen puede apuntar a un enlace: ``[imagen.jpg www.url.net]``
  800. - Pueden usarse macros en las direcciones de los enlaces: ``[ver source% %infile]``
  801. - Pueden utilizarse macros en los nombres de enlaces: ``[mirror de %%outfile www.debian.org]``
  802. % - Beautifiers are allowed on the link name: ``[**click** here www.url.com]``
  803. - El enlace debe ser especificado en una sola línea, sin saltos de línea
  804. - **Detalles:**
  805. - Si el archivo final no soporta enlaces, éstos serán subrayados.
  806. ---------------------------------------------------------------------
  807. == Cita ==[mark-quote]
  808. - **Descripción:** Identifica una línea de cita (indentada).
  809. - **Propiedades:**Multiline, !FreeSpaces, !Align, Nesting
  810. - **Contenido:** Macros, Modificadores de Fuentes, Cita, Raw, Barras, Enlaces, Imágen, Comentarios
  811. - **Sintaxis:**
  812. - Una línea que comienza por una tabulación (TAB)
  813. - A más TABs, mayor "profundidad"
  814. - No se permiten listas ni tablas
  815. - **Detalles:**
  816. - Si el final del archivo fuente es activado (EOF) , se cierra la cita abierta
  817. - No hay límites en los niveles de cita, pero algunos tipos de archivos destino no soportan determinados niveles de cita. En estos casos, las sub-citas no soportadas son transformadas al nivel superior
  818. ---------------------------------------------------------------------
  819. == Listas, Listas Numeradas, Listas de Definición ==[mark-lists]
  820. - **Descripción:** Identifica el comienzo de una lista de elementos
  821. - **Propiedades:** Multiline, !FreeSpaces, !Align, Nesting
  822. - **Contenido:**Macros, Modificadores de Fuentes, Listas, Tabla, Raw, Barras, Enlaces, Imágen, Comentario
  823. - **Sintaxis:**
  824. - Una línea que comienza por la siguiente secuencia: guión "-" /dos puntos ":" / seguida de, exactamente, un espacio
  825. - El primer carácter de la lista no puede ser un espacio (excepción: listas de definición)
  826. - Espacios (no TAB) al principio de la línea definen la profundidad (niveles) de las sub-listas (anidamiento)
  827. - Las sub-listas se acaban con un elemento de menor profundidad o con un elemento vacio
  828. - Todas las listas abiertas se cierran con dos lineas en blanco consecutivas
  829. - **Detalles:**
  830. - Si el final del archivo fuente es activado (EOF) se cierran todas las listas abiertas
  831. - Las listas pueden ser mixtas, por ejemplo, una lista de definición en una lista numerada
  832. - Algunos tipos de archivos finales no admiten la imbricación de listas, los elementos de las sub-listas son transformados al nivel superior..
  833. - No hay restricción en la profundidad de las listas, pero ciertos tipos de archivos destino tienen restricciones al respecto. En estos casos, las sub-listas de nivel inferior son ascendidas
  834. ---------------------------------------------------------------------
  835. == Imágen ==[mark-image]
  836. - **Descripción:**Identifica una imágen
  837. - **Propiedades:** !Multiline, !FreeSpaces, Align, !Nesting
  838. - **Contenido:**Macros
  839. - **Sintaxis:**
  840. - Un archivo de imágen encerrado entre corchetes: ``[imagen.jpg]``
  841. - El archivo de imágen debe acabar con una extensión del tipo PNG, JPG, GIF,.....(en mayúsculas o minúsculas, indiferentemente)
  842. - Se admiten símbolos en el nombre del archivo de imágen: ``[ imagen~!tres.jpg]``
  843. - Se admiten macros en el nombre del archivo de imágen: ``[report-%%date(%Y-%m-%d).png]``
  844. - No se admiten espacios en el nombre del archivo de imágen: ``[como esta.jpg]``
  845. - No se admiten espacios entre el corchete y el nombre del archivo de imágen: ``[ likethis.jpg ]`` es incorrecto
  846. - **Detalles:**
  847. - Si el archivo destino no admite imágenes, el nombre del archivo de la imágen se presenta entre (paréntesis)
  848. - La posición de las marcas indica el alineamiento de la imágen:
  849. - ``[IZQUIERDA.jpg]`` blablablabla
  850. - blablabla ``[CENTRO.jpg]`` blablabla
  851. - blablablabla ``[DERECHA.jpg]``
  852. ---------------------------------------------------------------------
  853. == Tabla ==[mark-table]
  854. - **Descripción:** Delimita una fila de una tabla, de cualquier número de colunas.
  855. - **Propiedades:** Multiline, FreeSpaces, Align, !Nesting
  856. - **Contenido:** Macros, Modificadores de Fuentes, Raw, Enlaces, Comentario.
  857. - **Sintaxis:**
  858. - Una línea vertical "|" identifica una fila de una tabla.
  859. - Dos líneas verticales "||" al principio de una línea identifica la fila de cabecera de una tabla
  860. - Los espacios delante de la primera línea vertical personalizan el centrado de la tabla
  861. - Los campos están separados por la cadena espacio/barra vertical/espacio " | "
  862. - Una barra vertical "|" al final de la primera fila de una tabla hace visibles los bordes
  863. - La barra-vertical al final de otras filas de la tabla es ignorada (sólo tiene efectos "cosméticos)
  864. - Cerrando una celda con más de una barra vertical determina la expansión de columna (column span) : "||" para dos columnas, "|||" para tres columnas, etc....
  865. - Los espacios(no TAB) en el interior de las celdas determinan su alineamiento.
  866. - Ejemplo: ``| fila | de | tabla | con | seis | columnas |``
  867. - **Detalles:**
  868. - Cada fila de tabla debe estar en una sóla línea del archivo fuente, sin saltos de línea
  869. - Los archivos destino con alineamiento por columnas (como sgml y LaTeX) usan el alineamiento de la primera fila como referencia para las demás.
  870. - Toda línea "no-tabla" cierra la tabla abierta, con excepción de las líneas de comentario
  871. - El número de celdas es flexible.Cada fila puede contener un número distinto de celdas
  872. - No hay un modo de especificar la anchura de las columnas.
  873. - Si el archivo destino no admite tablas, las filas de la tabla son consideradas como una zona verbatim
  874. ---------------------------------------------------------------------
  875. == Raw,Líneas y Zonas Raw (tal-cual) ==[mark-raw]
  876. - **Descripción:**Utilizado para proteger texto del archivo fuente, de manera que las marcas y macros que contenga no sean tratados
  877. - **Propiedades:**!Multiline, !FreeSpaces, !Align, !Nesting
  878. - **Contenido:** --
  879. - **Sintaxis:Raw:**
  880. - Dos dobles-comillas alrededor del texto: ``""""como ésto""""``
  881. - Sin espacios entre las marcas y el texto
  882. - **Sintaxis:Línea Raw:**
  883. - Una línea que comieza con 3 dobles-comillas consecutivas:``""" línea``
  884. - La marca debe estar en la primera columna de la línea, sin espacios delante
  885. - Utilizar un espacio después de la marca para separar la del texto
  886. - **Sintaxis:Zona Raw:**
  887. - Una línea que comieza con 3 dobles-comillas consecutivas, seguidas de la línea de texto, seguida de otras 3 dobles-comillas consecutivas.
  888. - Sin espacios antes o después de las marcas
  889. - **Detalles:**
  890. - Las marcas no son interpretadas
  891. - Las macros no son interpretadas
  892. - Si el final del archivo fuente es activado (EOF) se cierra la zona raw abierta
  893. =======================================================================
  894. = Parte VI - Dominando las Macros =[macros]
  895. Las macros son palabras-clave específicas que son utilizadas por el programa, en el momento de la conversión, para insertar informaciones dinŕmicas tales como la fecha e informaciones referentes al documento fuente o al documento final.
  896. Una macro está constituida por los carácteres ``%%`` seguidos de su nombre, por ejemplo, ``%%date``. Algunas macros aceptan una cadena de formato entre paréntesis, justo después del nombre de la macro, como, por ejemplo: ``%%date(%Y-%m-%d)``. Ésta cadena de formato incluye texto clásico junto con directivas, identificadas por ``%``, seguidas de un carácter de identificación. Si no se especifica ninguna cadena de formato, se utilizará el formato por defecto.
  897. || Nombre Macro | Se transforma en... | Formato por defecto |
  898. | ""%%date"" | Fecha actual | %Y%m%d
  899. | ""%%mtime"" | Fecha de modificacion del archivo fuente | %Y%m%d
  900. | ""%%infile"" | Path al archivo fuente | %f
  901. | ""%%outfile"" | Path al archivo final | %f
  902. | ""%%toc"" | Índice de contenidos del documanto (TOC) | -
  903. Reglas generales:
  904. - El nombre de la macros es insensible a la caja: ``%%date`` y ``%%DaTe`` son idénticas
  905. - Las macros son válidas en las áreas del Encabezamiento y del Cuerpo del documento, excepto ``%%toc``, que sólo es válida en el área del Cuerpo.
  906. - Una macro que se encuentre en la zona de Configuración se ejecutará en la zona del Cuerpo.
  907. - Una macro puede situarse en cualquier parte de una línea.
  908. - Una línea puede contener varias macros. Excepción: ``%%toc``, que debe estar sóla en la línea
  909. - Una macro puede utilizarse en los enlaces y en las marcas de imágen (excepto ``%%toc``)
  910. - Las macros no son procesadas en los títulos ni en las zonas Verbatim y Raw
  911. Ejemplo (el texto en negrita ha sido generado por macros):
  912. Esto es la guia del Usuario de Txt2tags,convertida a **%%outfile(%e)**
  913. por txt2tags a partir del archivo fuente **%%infile** . La conversión se realizó en fecha
  914. **%%date(%Y-%m-%d %X)**, los últimos cambios en el documento fuente fueron realizados el
  915. **%%mtime(%Y-%m-%d %X)**. Tanto el archivo fuente como el final se encuentran en el directorio **%%infile(%D)**
  916. -----------------------------------------------------------------------
  917. == %%date ==[macro-date]
  918. Llamada sin ninguna directiva especiál, ``%%date`` nos devuelve la fecha actual con el formato ISO yyyymmdd. Puede cambiarse el formato usando la sintaxis ``%%date(formato)``
  919. Esta macro acepta un amplio conjunto de directivas. Puede encontrarse un listado completo de estas directivas en
  920. la web de [Phyton http://www.python.org/doc/current/lib/module-time.html].
  921. Éstas son las directivas usadas com mayor frecuencia:
  922. || Directiva | Descripción |
  923. | %a | Nombre abreviado del día de la semana.
  924. | %A | Nombre completo del día de la semana.
  925. | %b | Nombre abreviado del més.
  926. | %B | Nombre completo del més.
  927. | %c | Representacion del día y hora, con formato apropiado.
  928. | %d | Día del més en formato decimal [01,31].
  929. | %H | Hora (modo 24-horas) en formato decimal [00,23].
  930. | %I | Hora (modo 12-horas) en formato decimal [01,12].
  931. | %m | Mes en formato decimal [01,12].
  932. | %M | Minutos en formato decimal [00,59].
  933. | %p | Equivalente locál tanto para AM como PM.
  934. | %S | Segundos en formato decimal[00,61]. (1)
  935. | %x | Representación apropiada de la fecha local.
  936. | %X | Representación apropiada de la hora local.
  937. | %y | Ańo, sin las cifras de la centuria, en formato decimal [00,99].
  938. | %Y | Ańo, con las cifras de la centuria, en formato decimal
  939. | %% | El carácter %
  940. Ejemplos
  941. || Macro | --> | Resultados convertidos en %%date(%Y, %b %d at %H:%M) |
  942. | ""%%date(Convertido en: %c)"" | --> | %%date(Convertido en: %c)
  943. | ""%%date(%Y-%m-%d)"" | --> | %%date(%Y-%m-%d)
  944. | ""%%date(%I:%M %p)"" | --> | %%date(%I:%M %p)
  945. | ""%%date(Hoy es %A, on %B.)"" | --> | %%date(Hoy es %A, on %B.)
  946. -----------------------------------------------------------------------
  947. == %%mtime ==[macro-mtime]
  948. Esta macro nos devuelve la fecha de la última modificación del archivo fuente. Acepta las mismas directivas de formato que [""%%date"" macro #macro-date].
  949. Ejemplo:
  950. Esta Guía del Usuario fué editada por última vez el
  951. **%%mtime(%c)**. Esta fecha ha sido generada por ``%%mtime(%c)``.
  952. -----------------------------------------------------------------------
  953. == %%infile ==[macro-infile]
  954. Nos devuelve el camino (PATH) al archivo fuente en el sistema. Es útil para hacer cosas como "mira la fuente de este archivo" en enlaces de páginas HTML. Dar esta información es un detalle amable hacia los debutantes, que podrŕn utilizar vuestra fuente como ejemplo para sus propias páginas.
  955. Esta macro acepta las siguientes directivas de formato:
  956. || %<char> | Descripción | output generado para esta Guia del Usuario |
  957. | %f | Nombre del archivo | %%infile(%f)
  958. | %F | Nombre del archivo (sin extension) | %%infile(%F)
  959. | %e | Extensión del archivo | %%infile(%e)
  960. | %p | Path absoluto al archivo | %%infile(%p)
  961. | %d | Path al archivo (sólo directorios) | %%infile(%d)
  962. | %D | Path al archivo (sólo directorio padre) | %%infile(%D)
  963. | %% | Carácter % | %%infile(%%)
  964. Ejemplos:
  965. || Fuente | --> | Resultado |
  966. | El directorio padre de esta guia es ""%%infile(%D)"". | --> | El directorio padre de ésta Guía es %%infile(%D). |
  967. | Usa la extensión ""%%infile(%e)"" . | --> | Usa la extensión %%infile(%e). |
  968. | ""[Consulta la fuente %%infile]"" | --> | [Consulta la fuente %%infile]
  969. | Convertido a XHTML, Se llamará ""%%infile(%F)"".xhtml | --> | Convertid a XHTML, se llamará %%infile(%F).xhtml
  970. Nota: La macro nos devuelve "-" si el archivo fuente es STDIN.
  971. -----------------------------------------------------------------------
  972. == %%outfile ==[macro-outfile]
  973. Nos devuelve el camino (PATH) al archivo convertido, en el sistema. Es práctico colocado en las áreas de Encabezamiento y el Cuerpo del archivo.
  974. Acepta las mismas directivas que la macro [ ""%%infile"" #macro-infile]
  975. Ejemplos:
  976. || Fuente | --> | Resultado |
  977. | Estás leyendo el archivo ""%%outfile"" . | --> | Estás leyendo el archivo %%outfile .
  978. | txt2tags -t ""%%outfile(%e)"" -i ""%%infile"" -o ""%%outfile"" | --> | txt2tags -t %%outfile(%e) -i %%infile -o %%outfile
  979. Nota: La macro nos devuelve "-" si el archivo fuente es STDOUT
  980. -----------------------------------------------------------------------
  981. == %%toc ==[macro-toc]
  982. Esta macro nos devuelve el índice de materias del documento. Es útil para indicarnos donde lo queremos insertar.
  983. Puedes utilizar esta macro más de una vez para, por ejemplo, insertar el índice de materias al inicio y al final del documento . Esta Guia esta utilizando ``%%toc`` para insertar el ěndice de materias
  984. A diferencia de otras macros, no acepta directivas de formato y se rige por unas reglas especiales:
  985. - Sólo es válida si se coloca en el **Area del Cuerpo** del documento
  986. - Debe encontrarse sóla en la línea ( se permiten espacios antes y después de la macros)
  987. - Debe utilizarse con la opción en línea de comandos --toc, si no, será ignorada.
  988. - El posicionamiento y el formato por defecto del Ěndice de materias, se ignorarán cuando se encuentre una macro ``%%toc``.
  989. =======================================================================
  990. = Parte VII - Dominando las Directivas de Configuración =[settings]
  991. Las Directivas de Configuración son directivas especiales, localizadas en en **Area de Configuración** del documento fuente, que afectan al comprotamiento de la conversión.
  992. Las Directivas de Configuración son todas opcionales. Cualquier usuario medio puede generar documentos txt2tags sin siquiera conocer la existencia de dicha Directivas, pero, como ya se ha dicho anteriormente, el usuario que las haya "experimentado" dificilmente podrá prescindir de las ventajas y el control que le proporcionan.
  993. Las Directivas de Configuración se escriben como //líneas de comentario especiales//, precedidas de la marca ("!") que las diferencia de los comentarios clásicos.
  994. La sintaxis es tan simple como la de la asingación de un valor a una variable:
  995. || %! palabra-clave : valor |
  996. Detalles de la sintaxis:
  997. - No debe haber espacio entre el carácter de comentario y el signo de exclamación ("%!")
  998. - Los espacios entre la clave y el separador (":") son opcionales
  999. - La clave y el valor son insensibles a la caja ( no distinguen entre mayúsculas y minúsculas)
  1000. Reglas:
  1001. - Sólo son válidas en el **Area de Configuracón**. Si se emplazan en otra área del documento serán tratadas como comenterios
  1002. - Si la misma directiva aparece varias veces en el **Area de Configuración**, sólo se tomará en consideración la última. Excepción: options, preproc y postproc, que son acumulativas
  1003. - Una directiva con una clave no válida será considerada un comentario
  1004. - Las directivas tienen prioridad sobre el archivo RC pero no sobre las opciones en línea de comandos
  1005. -----------------------------------------------------------------------
  1006. == %!Target ==[setting-target]
  1007. Usando la configuración target se define un formato para el documento destino:
  1008. ``` %!target: html
  1009. Asi, al usuario le bastará con ordenar
  1010. ``` $ txt2tags file.t2t
  1011. Y la conversión se realizará al formato especificado en target
  1012. Target no permite una especificación opcional de destino. Asi, no tendra sentido: ``%!target(tex): html``.
  1013. -----------------------------------------------------------------------
  1014. == %!Options ==[setting-options]
  1015. Tener que escribir largas líneas de comando cada vez que sea necesario convertir un documento, además de cansado puede ser fuente de numerosos errores. La configuración ``%!options`` permite que el usuario guarde, en el propio documento origen, todas las opciones de configuración que necesitará. Esto es garantia, además, de que el documento será siempre convertido de la misma forma, con las mismas opciones.
  1016. Las opciones deben escribirse como se haria en la línea de comandos, sin errores sintacticos. Pero no debe incluirse la llamada al programa "txt2tags" ni el nombre del archivo origen al final de la línea.
  1017. Si en línea de comandos se utiliza la siguiente orden:
  1018. ``` $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t
  1019. En la configuración ``%!options`` deberá escribirse:
  1020. ```
  1021. %!target: html
  1022. %!options(html): --toc --toc-level 2 --enum-title
  1023. ```
  1024. La línea de comandos, para la conversión del documento que incluya la configuración ``%!options``, pasa a ser "txt2tags file.t2t", y la conversión puede ser ejecutada dentro nuestro editor de texto preferido mientras el contenido está siendo editado. En Vi, el comando es:
  1025. ``` :!txt2tags %
  1026. -----------------------------------------------------------------------
  1027. == %!Encoding ==[setting-encoding]
  1028. La configuración de ``%!encoding`` es casi imprescindible para aquellos autores que escriben en idiomas que contemplan letras acentuadas y otros detalles específicos, de forma que el Conjunto de Caracteres del documento final pueda ser personalizado.
  1029. Los valores válidos para la configuración de ``%!encoding`` son los mismos que para documentos HTML, (iso-8859-1, UTF-8, koi8-r, etc. ).
  1030. En la siguiente dirección pude consultarse la lista de [códigos http://www.iana.org/assignments/character-sets]
  1031. El documento final LaTex utiliza alias para la codificación . Esto no representa ningún problema para el usuario,ya que txt2tags los traduce intennamente.
  1032. Algunos ejemplos de esta traducción son los que a continuación se relacionan:
  1033. || txt2tags/HTML | > | LaTeX |
  1034. | windows-1250 | >>> | cp1250 |
  1035. | windows-1252 | >>> | cp1252 |
  1036. | ibm850 | >>> | cp850 |
  1037. | ibm852 | >>> | cp852 |
  1038. | iso-8859-1 | >>> | latin1 |
  1039. | iso-8859-2 | >>> | latin2 |
  1040. | koi8-r | >>> | koi8-r |
  1041. Si el valor es no es reconocido por txt2tags, será pasado sin codificar, permitiendo al usuario especificar codificaciones personalizadas.
  1042. -----------------------------------------------------------------------
  1043. == %!PreProc ==[setting-preproc]
  1044. Es un filtro con la función "busca y cambia", que es aplicada en el documento original, después de que la línea haya sido leída y antes de cualquier tratamiento por txt2tags.
  1045. Es útil para definir algunas abreviaciones para texto que sea de uso frecuente, como:
  1046. ```
  1047. %!preproc JJS "John J. Smith"
  1048. %!preproc RELEASE_DATE "2003-05-01"
  1049. %!preproc BULLET "[images/tiny/bullet_blue.png]"
  1050. ```
  1051. Si el usuario escribe una línea como ésta :
  1052. ``` ĄHola! Me llamo Antoni. Hoy es RELEASE_DATE.
  1053. txt2tags la presentará como :
  1054. ``` ĄHola! Me llamo Antoni. Hoy es 2003-05-01.
  1055. Este filtro es un componente que trabaja entre el autor del documento y la conversión de txt2tags. Es una espécie de "primera conversión" antes de la conversión definitiva. Este componente funciona exactamente como un filtro Sed/Perl externo, que se invocan de la siguiente forma:
  1056. ``` $ cat ARCHIVO.t2t | preproc-script.sh | txt2tags -
  1057. El tratamiento ejecutado por txt2tags comenzará una vez todas las sustituciones PreProc hayan sido realizadas.
  1058. -----------------------------------------------------------------------
  1059. == %!PostProc ==[setting-postproc]
  1060. Es un filtro con la funcion "busca y sustituye", que es aplicada al archivo resultante, una vez realizadas todas las conversiones por txt2tags.
  1061. Es útil para definir algunos refinamientos en el documento generado, cambiar algunas marcas, ańadir texto extra, etc. Algunos breves ejemplos:
  1062. ```
  1063. %!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">'
  1064. %!postproc(tex) : "\\newpage" ""
  1065. ```
  1066. Estos filtros cambian el color de fondo de la pagina HTML y eliminan los saltos de página en archivos LaTex generados.
  1067. Las reglas de PostProc son las mismas que las de los filtros externos Sed/Perl, que se invocan de la siguiente forma:
  1068. ``` $ txt2tags -t html -o- file.t2t | postproc-script.sh > file.html
  1069. Antes de que apareciera esta funcionalidad, era bastante común tener pequeńos scripts para "ajustar" los resultados generados por txt2tags. Dichos scripts eran, de hecho, varios comandos sed ( o simlares), para hacer algo parecido a "sustituye esto por aquello". Actualmente las órdenes para estas sustituciones pueden ser guardadas junto con el texto del documento, y también aprovechase de la poderosa maquina de Expresiones regulares de Python.
  1070. -----------------------------------------------------------------------
  1071. == %!Style ==[setting-style]
  1072. - Esta opción es útil en la generacion de archivos HTML y XHTML, definiendo el nombre del archivo CSS que sera usado por el documento generado.
  1073. - En el formato LaTex, esa opción se usa para cargar modulos ``/usepackage``.
  1074. - El mismo resultado se obtiene con la opción en línea de comandos --style
  1075. - La opcion --style en línea de comandos tiene preferencia sobre la configuración de ``%!style``.
  1076. -----------------------------------------------------------------------
  1077. == Definiendo una Configuración para un Tipo de Archivo Destino Específico ==[setting-specific]
  1078. Desde la versión 1.6 de txt2tags, todas las Directivas de Configuración, excepto ``%!target``, pueden ser especificadas para un tipo de archivo destino especifico, usando la sintaxis : ``%!clave(destino):valor``. De esta forma, el usuario puede definir diferentes configuraciones para diferentes tipos de archivos generados.
  1079. Éste es un aspecto especialmente útil en los filtros pre/postproc, aunque puede ser utilizado en todas las directrices. Por ejemplo, configurar diferentes estilos para HTML y LaTeX:
  1080. ```
  1081. %!style(html): fancy.css
  1082. %!style(tex) : amssymb
  1083. ```
  1084. Para ajustar las opciones en el documento convertido, algo como ésto puede ser útil:
  1085. ```
  1086. %!target: sgml
  1087. %!options(sgml): --toc
  1088. %!options(html): --style foo.css
  1089. %!options(txt ): --toc-only --toc-level 2
  1090. ```
  1091. De esta forma, el tipo de destino patrón es SGML y generará un índice de materias (TOC).
  1092. Si el usuario ejecuta:
  1093. ``$ txt2tags -t html file.t2t``
  1094. El tipo de destino será HTML y solamente serán usadas las opciones de ``%!options(html)`` . De esta forma se utilizará la opcion --style y en el archivo HTML no se generará un índice de materias.
  1095. -----------------------------------------------------------------------
  1096. == Detalles de los filtros PreProc y PostProc ==[filters-details]
  1097. - Los filtros contienen una función de "buscar y sustituir".
  1098. - No son del tipo "utiliza la última encontrada", ya que son acumulativos. Podemos definir tantos filtros como deseemos. Serán aplicados todos, en el orden en que hayan sido definidos.
  1099. - Para los filtros, el orden de definición marca su aplicación y seran aplicadas tanto las reglas genéricas como las específicas al tipo-destino. En el siguente ejemplo, ambos filtros son aplicados en el documento HTML final:
  1100. ```
  1101. %!postproc : this that
  1102. %!postproc(html): that other
  1103. ```
  1104. - Los filtros deben recibir exactamente dos argumentos.
  1105. - Escapes especiales como ``\n`` y ``\t`` también son interpretados.
  1106. - Para eliminar texto, sustitúyelo por una cadena vacía
  1107. ``` %!postproc: "texto no deseado" ""
  1108. - Para evitar problemas, procura siempre indicar explicitamente el destino al que se aplicará el filtro cuando se esté usando
  1109. PostProc para cambiar marcas: ``%!PostProc(destino): <esto> <aquello>``
  1110. - PreProc es aplicado después de que una línea haya sido leída. PostProc es aplicado después de que todo el tratamiento se haya realizado. Funcionan exactamente como en:
  1111. ``` $ cat file.t2t | preproc.sh | txt2tags | postproc.sh
  1112. - La primera parte de un filtro ( la cadena "busca"), no es leída como una cadena sino como una expresión regular. Si no sabes lo que es ésto, no te preocupes, casi seguro que nunca trendrás necesidad de ello. Pero recuerda que que debes "escapar" los carácteres para el usuario. "Escapar"significa preceder el carácter con el signo "\". Cómo en la siguiente lista:
  1113. ``` \* \+ \. \^ \$ \? \( \) \{ \[ \| \\
  1114. - Las Expresiones Regulares de Python pueden ser utilizadas. Son similares a las Regex de Perl. Por ejemplo: cambia todas las marcas "B" para "STRONG" en HTML:
  1115. ``` %!postproc(html): '(</?)B>' '\1STRONG>'
  1116. - Los argumentos de los filtros pueden ser pasados de tres formas:
  1117. + Una palabra simple, sin apóstrofes ni comillas, como FOO (sin espacios)
  1118. + Una cadena con dobles comillas, como en "FOO"
  1119. + Una cadena ,con comillas o apóstrofes,como en 'FOO'
  1120. - Si la expresión origen tiene apóstrofes, protéjelos con comillas y vice-versa. Algunos ejemplos:
  1121. ```
  1122. %!postproc: ORIGEN CAMBIO
  1123. %!postproc: "ORIGEN" "CAMBIO"
  1124. %!postproc: 'ORIGEN' 'CAMBIO'
  1125. %!postproc: ORIGEN "CAMBIO"
  1126. %!postproc: "ORIGEN" 'CAMBIO'
  1127. ```
  1128. =======================================================================
  1129. = Parte VIII - Mágia Negra =[black-magic]
  1130. Este no es un capítulo recomendado para novatos. Aquí se va a mostrar como hacer cosas "extrańas" con los filtros de txt2tags, "abusando" de patrones complejos y de Expresiones Regulares.
  1131. **ĄAtencion!** Los procedimientos detallados a continuación pueden acarrear dańos. Algún texto puede perderse en el procedimiento de conversión, no apareciendo en el documento generado. Usa estos procedimientos sólo si precisas verdaderamentede ellos y/o si sabes exactamente lo que estas haciendo
  1132. || Los filtros son un procedimiento poderoso, pero pueden ser peligrosos |
  1133. || Los filtros mal usados generan resultados inesperados |
  1134. -----------------------------------------------------------------------
  1135. == Insertando Múltiples Líneas con %!PostProc (como reglas CSS) ==[postproc-multiline]
  1136. En los filtros, el patrón de sustitución puede incluir múltiples líneas utilizando el carácter de salto de línea ``\n``
  1137. Esta funcionalidad puede ser útil para incluir reglas CSS en un archivo HTML generado, sin necesidad de crear un archivo separado. Este es el caso de esta Guia del Usuario, que utiliza los siguientes filtros:
  1138. ```
  1139. %!postproc: <HEAD> '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>'
  1140. %!postproc: (</STYLE>) 'body { margin:3em ;} \n\1'
  1141. %!postproc: (</STYLE>) 'a { text-decoration:none ;} \n\1'
  1142. %!postproc: (</STYLE>) 'pre,code { background-color:#ffffcc ;} \n\1'
  1143. %!postproc: (</STYLE>) 'th { background-color:yellow ;} \n\1'
  1144. ```
  1145. Todos los filtros están subordinados al primero, para reemplazar una cadena que ha insertado. De esta forma, un simple "<HEAD>" se transforma en:
  1146. ```
  1147. <HEAD>
  1148. <STYLE TYPE="text/css">
  1149. body { margin:3em ;}
  1150. a { text-decoration:none ;}
  1151. pre,code { background-color:#ffffcc ;}
  1152. th { background-color:yellow ;}
  1153. </STYLE>
  1154. ```
  1155. -----------------------------------------------------------------------
  1156. == Creando Contenido "Específico al Tipo Destino" con %!PreProc ==[target-specific-contents]
  1157. Algunas veces es necesario insertar algún texto solo para un tipo de destino específico y no para otros. Este tipo de comportamiento "extrańo" puede ser llevado a cabo con PreProc.
  1158. La idea es insertar este texto extra en el archivo original como comentario, pero marcarlo de forma que un filtro especifíco para aquel tipo de destino lo "descomente"
  1159. Por ejemplo, si debe insertarse un párrafo extra solamente en el tipo de destino HTML, coloca el texto en un comentario especial como este:
  1160. ```
  1161. %html% Esta página HTML fué generada por [txt2tags http://txt2tags.org].
  1162. %html% Vea el archivo fuente TXT [aqui source.t2t].
  1163. ```
  1164. Como todas las líneas comienzan con ``%``, son líneas de comentario y serán ignoradas.
  1165. Pero si ańadimos este filtro especial:
  1166. ``` %preproc(html): '^%html% ' ''
  1167. El signo ``%`` inicial es eliminado, "activando" las líneas que lo contenian, que dejarán de ser comentarios para pasar a integrar el texto del documento final. Como hemos configurado un destino específico, HTML, el filtro sólo se aplicará a él.
  1168. -----------------------------------------------------------------------
  1169. == Cambiando Marcas txt2tags con %!PreProc ==[creating-marks]
  1170. Si el usuario es un gurú de Expresiones Regulares, podria personalizar la sintaxis del documento, cambiando las marcas txt2tags patrón por algo que le fuere mas confortable.
  1171. Por ejemplo, una TAB es una marca de cita. Si al usuario no le gusta eso, puede definir una nueva marca para el "texto citado". Consideremos que escoja colocar ">>>" . Precisará de este filtro simple:
  1172. ``` %!PreProc: '>>> ' '\t'
  1173. Y en el documento original, el "texto citado" aparecera como:
  1174. ```
  1175. >>> Este es un texto citado
  1176. >>> El usuario definio esta marca exquisita
  1177. >>> Pero seran convertidas a TABs por PreProc
  1178. ```
  1179. Antes que el analisis del programa comience, las ">>>" seran transformadas en TABs y txt2tags reconocera la marca de cita.
  1180. **ĄAtencion!** Las Reglas PreProc extremas pueden ,eventualmente, cambiar toda la sintaxis de marcado y asi mismo, generar conflictos entre marcas. Ten mucho cuidado en la utilizacion de estas reglas.
  1181. =======================================================================
  1182. = Parte IX - História de Txt2tags =[history]
  1183. En júlio de 2001 se lanzó al público la primera versión de txt2tags (v0.1). Pero sus orígenes se remontan a más de un ańo antes de aquel día.
  1184. Este capítulo ilustra, en pocas palabras, el desarrollo de esta herramienta, desde que la primera línea fué escrita hasta la actual versión.
  1185. == Enero de1999: Pre-História ==[history-1999-1]
  1186. "Mi primera tentativa de hacer una herramienta de conversión comenzó en 1999, como un simple script
  1187. Bourne Shell que convertía texto con marcas en una página HTML. Cómo otra herramienta txt2html.
  1188. Todo el mundo debe haber hecho ya una de estas herramientas......En resumen, reconocia marcas simples, como ``*bold*``,
  1189. ``/italic/``, ``_subrayado_``, y escapaba los carácteres especiales ``< & >`` de HTML. Nada impresionante, pero era joven;)"
  1190. == Júnio de 1999: Todavía Pre-História ==[history-1999-2]
  1191. % scripts/antigos/txt2sgml-bash/txt2sgml 25/06/1999
  1192. "Pasaron algunos meses, y un gran "hype" entorno a Sgml llegó a la compańia en la que
  1193. estaba trabajando (Conectiva). Txt2tags se transformó en un script txt2sgml. Estaba realmente tentado a aprender
  1194. sobre SED* en aquel tiempo, de forma que txt2tags en aquella época era un script Bourne Shell con mucho código SED"
  1195. * **SED:** UNIX Stream EDitor - una herramienta de edición automática de textos
  1196. Esta versión mejorada, con soporte Sgml, ofrecía soporte a más estructuras como listas y texto preformateado.
  1197. En el siguiente archivo ejemplo, pueden verse los orígenes delas marcas txt2tags:
  1198. ```
  1199. * Esta es una línea en negrita (żNEGRITA orientada a línea? bien...)
  1200. --
  1201. - lista no numerada muy semejante a lista de txt2tags
  1202. - pero con éstos -- para iniciar y terminar la lista
  1203. --
  1204. =----------------------
  1205. El texto preformateado era delimitado por el patrón =-- .
  1206. Los otros ------- eran cosméticos.
  1207. =----------------------
  1208. ```
  1209. Nada impresionante todavia, pero el gran paso esta al caer...
  1210. == Agosto de 2000: No más Pre-História ==[history-2000]
  1211. % verde666.org/sed/programas/txt2*/txt2sgml.sed 20000816 - 20010514
  1212. "Pasó un ańo y, durante este tiempo, estuve realmente encantado con SED.
  1213. El escript de shell txt2sgml.sh fué reescrito convirtiéndose en
  1214. a 350 líneas de puro script SED. Fueron ańadidas algunas funcionalidades como subsecciones,
  1215. reconocimiento de URL y sublistas. Durante al menos un ańo, usé y probé muchísimo dicho script
  1216. Un sencillo ejemplo de archivo txt2sgml.sed :
  1217. ```
  1218. * Hey, here are the first 3 magic lines
  1219. * The document title / author / date
  1220. * But they required those asterisks at the beginning
  1221. MAIN TITLE
  1222. Titles were made by uppercase-only lines. Subtitles were identified by
  1223. leading spaces. Each space denoted a new sublevel. The beautifiers:
  1224. *bold*, **strong**, "italic" and `typewriter`.
  1225. - lists
  1226. + sublists
  1227. = and subsublists (by identifier, not indentation)
  1228. Two blank lines to close lists. Links as www.example.com and e-mails
  1229. were recognized automagically by regular expressions. And there was a
  1230. strange image mark:
  1231. %%image: path/to/image.jpg
  1232. ```
  1233. == Mayo 2001: Pythonización e Idea Multi Formato de Destino ==[history-2001-1]
  1234. "Habia comenzado a escribir mi libro,
  1235. [ Expresiones Regulares http://guia-er.sf.net]
  1236. y usado el formato de marcado txt2sgml.sed.
  1237. De esta forma pude convertirlo a sgml (luego a HTML utilizando una herramienta sgml2html)
  1238. y chequear rapidamente en el navegador cómo habia quedado el libro.
  1239. Pero cómo "rápido" y "sgml2html" no casan,
  1240. modifiqué el script SED de txt2html.sed
  1241. generando directamente HTML. [...].
  1242. Mi editor usaba Adobe PageMaker para el formateo de libros, lo que era un problema para un chico linux como yo.
  1243. Pero me alegré cuando me enteré que PageMaker utilizaba un sistema de marcas semejante al de HTML,
  1244. entonces, comencé a cambiar mi script en una herramienta txt2pagemaker.sed.
  1245. Habia acabado por tener tres scrips SED similares, convirtiendo mis textos a sgml, HTML y PageMaker.
  1246. Se crearon algunos scripts más para extraer el índice de contenidos (TOC) del libro y para realizar post-formateos.
  1247. A mitad redacción del libro, tuve la idea de unirlos en una sóla herramienta y elegir Python como lenguaje. Nació TXT2TAGS"
  1248. == Júlio de 2001: séries 0.x: Debut de txt2tags (Lanzamiento Mundial) ==[history-2001-2]
  1249. % v0.1 26 Jul 2001
  1250. "El lanzamiento del libro impreso (31 de júlio)
  1251. y de la primera versión (0.1) de txt2tags 26 de júlio)fué asunto de días.
  1252. Uno dependía de otro, fueron desarrollados juntos. Para ésta entrega, junto con sgml, HTML y Pagemaker, se implementaron otros formatos de archivo destino: MoinMoin, MagicPoint y texto plano. En menos de un ańo se realizaron más versiones de la série
  1253. 0.x y el programa comenzó a crecer: nuevo formato UNIX Man page, macro ""%%date"", soporte para tablas, interfaz Web, alineamiento de imágen y generacón de índices de contenido (TOC).
  1254. En la versión 0.2 se ańadió un script de Shell para el manejo de operaciones de archivo y opciones en línea de comando.
  1255. Lo ańadí por que yo era un mago del shell y un novato de Python.
  1256. No es hasta la versión 0.9 cuando txt2tags se transforma en 100% código Python."
  1257. == Septiembre de 2002: séries 1.x : Crecimiento ==[history-2002]
  1258. "La idea txt2tags resultó ser una buena idea. Decidí tomármela en serio.
  1259. La siguiente etapa fue la de expandir el programa, dándolo a conocer: Ądocumentación!.
  1260. Fué lanzado el site del programa, se configuraron listas de correo (en ingles y portugués) y nació la Guia del Usuario
  1261. La base de usuarios creció y llegaron numerosas contribuciones. Sí!, pensé, está funcionando.
  1262. Las nuevas funcionalidades ańadidas a las versiones de la série 1.x incluyen: Interfaz Gráfica (GUI), compatibilidad Windows & Mac, formato de destino LaTeX, %!style , el comando include y los potentes filtros de Pre y Post proceso. "
  1263. == Júlio de 2004: séries 2.x : Maduración ==[history-2004]
  1264. "El crecimiento es duro y extrańo. żRecuerdas que dije que era un novato de Python?.
  1265. Ahora estoy mejor, pero los viejos fallos acumulados, y el reescribir la mayor parte del código lo hicieron inevitable. Esto
  1266. rompió la compatibilidad con algunas marcas, por lo que se creó un script actualizado. Se lanzó la versión 2.0. Con ella llegó
  1267. el formato XHTML, la validación de código W3C, i18n y el archivo RC. Un equipo de traductores hacen que el programa y su documentación sea traducida a varios idiomas. Se ańadió el formato de destino Lout y las nuevas macros ""%%mtime"", ""%%infile"", ""%%outfile"", y ""%%toc"". Continúa......
  1268. ========================================================================
  1269. The End.
  1270. %nopdf([see source userguide.t2t])
  1271. [../../img/t2tpowered.png]