userguide.html | searchcode

/doc/English/userguide/userguide.html

Large files files are truncated, but you can click here to view the full file
   1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2<!-- This document was generated from userguide.t2t -->
   3<HTML>
   4<HEAD>
   5<META NAME="generator" CONTENT="http://txt2tags.org">
   6<LINK REL="stylesheet" TYPE="text/css" HREF="userguide.css">
   7<TITLE>Txt2tags User Guide</TITLE>
   8</HEAD>
   9<BODY>
  10
  11<DIV CLASS="header" ID="header">
  12
  13
  14</DIV>
  15
  16<DIV CLASS="body" ID="body">
  17
  18<H1>About</H1>
  19
  20<P>
  21This is the <A HREF="http://txt2tags.org">txt2tags</A> User Guide, the
  22complete manual about the program.
  23</P>
  24
  25<UL>
  26<LI>User Guide official address:
  27  <A HREF="http://txt2tags.org/userguide">http://txt2tags.org/userguide</A>
  28<P></P>
  29<LI>User Guide PDF download:
  30  <A HREF="http://txt2tags.org/userguide/userguide.pdf">http://txt2tags.org/userguide/userguide.pdf</A>
  31</UL>
  32
  33<A NAME="intro"></A>
  34<H1>Part I - Introducing Txt2tags</H1>
  35
  36<A NAME="1st-questions"></A>
  37<H2>The First Questions You May Have</H2>
  38
  39<P>
  40This chapter is a txt2tags overview, that will introduce the program
  41purpose and features.
  42</P>
  43
  44<H3>What is it?</H3>
  45
  46<P>
  47Txt2tags is a text formatting and conversion tool.
  48</P>
  49
  50<DL>
  51<DT><B>A text formatting tool</B>: The txt2tags wiki-like syntax is easy to use and to remember. You can use it for every purpose, like storing your notes and formatting your documents.</DT><DD>
  52<P></P>
  53<DT><B>A conversion tool</B>: You can use the txt2tags python program to converts your txt2tags documents to several supported <A HREF="#targets">targets</A>. <I>(Further reference to the txt2tags python program will simply be labelled "txt2tags".)</I></DT><DD>
  54<P></P>
  55Amongs others, there are:
  56<P></P>
  57</DL>
  58
  59<UL>
  60<LI>popular Wiki markups, such as bbcode, wikipedia pages, markdown, restructuredtext and spip.
  61<P></P>
  62<LI>html variations: html transitional, xhtml, html5...
  63<P></P>
  64<LI>office documents: RTF, LaTeX documents, Open Document Spreadsheet, SQLite database (imported from tables)
  65<P></P>
  66<LI>plain text, including ASCII art variations.
  67</UL>
  68
  69<P>
  70<I>See the <A HREF="#targets">targets chapter</A> to discover the full list.</I>
  71</P>
  72
  73<DL>
  74<DT><B>And more</B>: Beyond those 2 aspects, which deals with defined features and syntax, txt2tags can also manipulate your document with <A HREF="#setting-preproc">powerful input and output filters</A>.</DT><DD>
  75</DL>
  76
  77<H3>Why should I use it?</H3>
  78
  79<P>
  80You'll find txt2tags really useful if you:
  81</P>
  82
  83<UL>
  84<LI>Need to publish documents in different formats
  85<LI>Need to maintain updated documents in different formats
  86<LI>Write technical documents or guides
  87<LI>Don't know how to write a document in a specific format
  88<LI>Don't have an editor for a specific format
  89<LI>Want to use a simple text editor to update your documents
  90</UL>
  91
  92<P>
  93And the main motivation is:
  94</P>
  95
  96<UL>
  97<LI>Save time, writing <B>contents</B> and forgetting about <B>formatting</B>
  98</UL>
  99
 100<H3>Why is it a good choice among other tools?</H3>
 101
 102<P>
 103Txt2tags has a very straight way of growing, following basic concepts.
 104These are the highlights:
 105</P>
 106
 107<TABLE>
 108<TR>
 109<TD><I>Source File Readable</I></TD>
 110<TD>Txt2tags marks are very simple, almost natural.</TD>
 111</TR>
 112<TR>
 113<TD><I>Target Document Readable</I></TD>
 114<TD>The target document is also readable, with indentation and spacing.</TD>
 115</TR>
 116<TR>
 117<TD><I>Consistent Marks</I></TD>
 118<TD>Txt2tags marks are simple symbols, designed to be unique enough to don't mix up with the document contents.</TD>
 119</TR>
 120<TR>
 121<TD><I>Consistent Rules</I></TD>
 122<TD>As the marks, the rules that applies to them are tied to each other, there are no "exceptions" or "special cases".</TD>
 123</TR>
 124<TR>
 125<TD><I>Simple Structures</I></TD>
 126<TD>All the supported formatting are <B>simple</B>, with no extra-options or complicated behavior modifiers. A mark is just a mark, with no options at all.</TD>
 127</TR>
 128<TR>
 129<TD><I>Easy to Learn</I></TD>
 130<TD>With simple marks and readable source, the txt2tags learning curve is user friendly.</TD>
 131</TR>
 132<TR>
 133<TD><I>Nice Examples</I></TD>
 134<TD>The <B>sample files</B> included on the package gives real life examples of documents written for txt2tags.</TD>
 135</TR>
 136<TR>
 137<TD><I>Valuable Tools</I></TD>
 138<TD>The <B>syntax files</B> included on the package help you to write documents with no syntax errors.</TD>
 139</TR>
 140<TR>
 141<TD><I>Three User Interfaces</I></TD>
 142<TD>There is a user friendly <B>Graphical interface</B>, a handy <B>Web interface</B> easy to install in intranets and a <B>Command Line interface</B> for power-users and scripting.</TD>
 143</TR>
 144<TR>
 145<TD><I>Scripting</I></TD>
 146<TD>With the full featured command line mode, an experienced user can <B>automatize</B> tasks and do <B>post-editing</B> on the converted files.</TD>
 147</TR>
 148<TR>
 149<TD><I>Download and Run / Multi-platform</I></TD>
 150<TD>Txt2tags is a single <B>Python script</B>. There is no need to compile it or download extra modules. So it runs nicely on *NIX, Linux, Windows and Macs.</TD>
 151</TR>
 152<TR>
 153<TD><I>Mature</I></TD>
 154<TD>First released in 2001, txt2tags is now a mature program with years of improvements and bug fixes, extensive documentation, translations and an loyal user base.</TD>
 155</TR>
 156</TABLE>
 157
 158<H3>Do I have to pay for it?</H3>
 159
 160<P>
 161Absolutely NO!
 162</P>
 163<P>
 164It's free, GPL licensed.
 165</P>
 166
 167<A NAME="structures"></A>
 168<H2>Supported Formatting Structures</H2>
 169
 170<P>
 171The following is a list of all the structures supported by txt2tags.
 172</P>
 173
 174<UL>
 175<LI>header (document title, author name, date)
 176<LI>section title (numbered or not)
 177<LI>paragraphs
 178<LI>font beautifiers
 179  <UL>
 180  <LI>bold
 181  <LI>italic
 182  <LI>underline
 183  <LI>strike
 184  </UL>
 185<LI>monospaced font (verbatim)
 186  <UL>
 187  <LI>monospaced inside paragraph
 188  <LI>monospaced line
 189  <LI>monospaced area (multiline)
 190  </UL>
 191<LI>quoted area
 192<LI>link
 193  <UL>
 194  <LI>URL/Internet links
 195  <LI>e-mail links
 196  <LI>local links
 197  <LI>named links
 198  </UL>
 199<LI>lists
 200  <UL>
 201  <LI>bulleted list
 202  <LI>numbered list
 203  <LI>definition list
 204  </UL>
 205<LI>horizontal separator line
 206<LI>image (with smart alignment)
 207<LI>table (with or without border, smart alignment, column span)
 208<LI>macros (with flexible formatting):
 209  <UL>
 210  <LI>current date
 211  <LI>file modification time
 212  <LI>input and output file name and path
 213  <LI>automatic table of contents
 214  </UL>
 215<LI>special mark for raw text (no marks parsed inside)
 216<LI>special mark for tagged text (no parsing, sent directly to output)
 217<LI>comments (for self notes, TODO, FIXME)
 218</UL>
 219
 220<A NAME="targets"></A>
 221<H2>Supported Targets</H2>
 222
 223<H3>Wiki</H3>
 224
 225<DL>
 226<DT><B>adoc</B></DT><DD>
 227  AsciiDoc document
 228<P></P>
 229<DT><B>bbcode</B></DT><DD>
 230  BBCode document
 231<P></P>
 232<DT><B>creole</B></DT><DD>
 233  Creole 1.0 document
 234<P></P>
 235<DT><B>DOKU</B></DT><DD>
 236  <A HREF="http://www.dokuwiki.org/dokuwiki">DokuWiki</A> is a standards
 237  compliant, simple to use Wiki, mainly aimed at creating documentation
 238  of any kind. It is targeted at developer teams, workgroups and small
 239  companies. It has a simple but powerful syntax which makes sure the
 240  data files remain readable outside the Wiki and eases the creation of
 241  structured texts. All data is stored in plain text files - no
 242  database is required.
 243</DL>
 244
 245<DL>
 246<DT><B>Foswiki / TWiki</B></DT><DD>
 247  <A HREF="http://foswiki.org/">Foswiki</A> or <A HREF="http://twiki.org">TWiki</A>, is a flexible, powerful, 
 248  and easy to use enterprise wiki and collaboration platform. 
 249  The structured wiki is typically used to run a project development 
 250  space, a document management system, a knowledge base, or any other 
 251  groupware tool, on an intranet or on the internet.
 252<P></P>
 253<DT><B>GWIKI</B></DT><DD>
 254  Now you can easily paste your project's current documentation into the
 255  <A HREF="http://code.google.com/">Google Code</A> Wiki.
 256<P></P>
 257<DT><B>md</B></DT><DD>
 258  Markdown document
 259<P></P>
 260<DT><B>MOIN</B></DT><DD>
 261  You don't know what <A HREF="http://moinmo.in/">MoinMoin</A> is?
 262  It is a <A HREF="http://www.c2.com/cgi/wiki">WikiWiki</A>!
 263<P></P>
 264  Moin syntax is kinda boring when you need to keep
 265  <CODE>{{{'''''adding braces and quotes'''''}}}</CODE>, so txt2tags comes with the
 266  simplified marks and unified solution: one source, multi targets.
 267<P></P>
 268<DT><B><A HREF="http://en.wikipedia.org/wiki/PmWiki">PMWIKI</A></B></DT><DD>
 269  <A HREF="http://www.pmwiki.org/">PmWiki</A> is a light and free wiki software written in PHP, and using no SQL database.
 270<P></P>
 271<DT><B>red</B> </DT><DD>
 272  Redmine Wiki page
 273<P></P>
 274<DT><B>rst</B></DT><DD>
 275  ReStructuredText document
 276<P></P>
 277<DT><B>spip</B></DT><DD>
 278  SPIP article
 279<P></P>
 280<DT><B>txt2t</B></DT><DD>
 281  Txt2tags document
 282<P></P>
 283<DT><B>WIKI</B></DT><DD>
 284  You've heard about the <A HREF="http://wikipedia.org">Wikipedia</A>, right? So you
 285  don't need to learn yet-another markup syntax. Just stick with txt2tags
 286  and let it convert your text to the Wikipedia format, called
 287  <A HREF="http://en.wikipedia.org/wiki/MediaWiki">MediaWiki</A>.
 288</DL>
 289
 290<H3>HTML</H3>
 291
 292<DL>
 293<DT><B>aapw</B></DT><DD>
 294  ASCII Art Presentation Web
 295<P></P>
 296<DT><B>aasw</B></DT><DD>
 297  ASCII Art Spreadsheet Web
 298<P></P>
 299<DT><B>aatw</B></DT><DD>
 300  ASCII Art Text Web
 301<P></P>
 302<DT><B><A HREF="http://en.wikipedia.org/wiki/HTML">HTML</A></B></DT><DD>
 303  You maybe know what HTML is. (hint: Internet)
 304<P></P>
 305  Txt2tags generates clean HTML documents, that look pretty and have
 306  its source readable. It DOES NOT use javascript, frames or other
 307  futile formatting techniques, that aren't required for simple, techie
 308  documents. But a separate CSS file can be used if wanted. Txt2tags
 309  generates "<I>HTML 4.0 Transitional</I>" code.
 310<P></P>
 311  Txt2tags HTML generated code is 100% approved by the <A HREF="http://validator.w3.org/">w3c validator</A>.
 312<P></P>
 313<DT><B>html5</B></DT><DD>
 314  HTML5 page
 315<P></P>
 316<DT><B>htmls</B></DT><DD>
 317  HTML Spreadsheet
 318<P></P>
 319<DT><B>wp</B></DT><DD>
 320  WordPress post
 321<P></P>
 322<DT><B><A HREF="http://en.wikipedia.org/wiki/XHTML">XHTML</A></B></DT><DD>
 323  It is the new generation of HTML, with more strict rules.
 324  This makes the code easier to parse and
 325  understand. For the general purpose, consider it HTML. Txt2tags
 326  generates "<I>XHTML 1.0 Transitional</I>" code.
 327<P></P>
 328  Txt2tags XHTML generated code is 100% approved by the <A HREF="http://validator.w3.org/">w3c validator</A>.
 329<P></P>
 330<DT><B>xhtmls</B></DT><DD>
 331  XHTML Strict page
 332</DL>
 333
 334<H3>Office</H3>
 335
 336<DL>
 337<DT><B>csv</B></DT><DD>
 338  CSV spreadsheet
 339<P></P>
 340<DT><B>db</B></DT><DD>
 341  SQLite database
 342<P></P>
 343<DT><B>dbk</B></DT><DD>
 344  DocBook document
 345<P></P>
 346<DT><B>LOUT</B></DT><DD>
 347  Very similar to LaTeX in power, but with an easier syntax using "@"
 348  instead "\" and avoiding the need of braces in common situations. Its
 349  approach of everything-is-an-object makes the tagging much saner.
 350<P></P>
 351  Txt2tags generates ready-to-use Lout files, which can be converted do
 352  PS or PDF files using the "lout" command.
 353<P></P>
 354<DT><B>MGP</B></DT><DD>
 355  <A HREF="http://en.wikipedia.org/wiki/MagicPoint">MagicPoint</A> is a very handy presentation tool
 356  (hint: Microsoft PowerPoint), that uses a tagged language to define all
 357  the screens. So you can do complex presentations in vi/emacs/notepad.
 358<P></P>
 359  Txt2tags generates a ready-to-use .mgp file, defining all the
 360  necessary headers for fonts and appearance definitions, as long as
 361  international characters support.
 362<P></P>
 363  Txt2tags creates "diet" .mgp files: they use the Type1 fonts, so you do not
 364  need to carry TrueType fonts files with your presentation. Also, the color
 365  definitions are simple, so even on a poor color palette system (such as
 366  <CODE>startx -- -bpp 8</CODE>), the presentation will look pretty!
 367<P></P>
 368  The key is: convert and use. No quick fixes or requirements needed.
 369<P></P>
 370<DT><B>ods</B></DT><DD>
 371  Open Document Spreadsheet
 372<P></P>
 373<DT><B>PM6</B></DT><DD>
 374  Adobe PageMaker 6.0 has its own tagged
 375  language. Styles, color table, beautifiers, and most of all the
 376  PageMaker mouse-clicking features are also available on its tagged language.
 377  You just need to access the "Import tagged text" menu item. Just for
 378  the records, it's an &lt;HTML "like"&gt; tag format.
 379<P></P>
 380  Txt2tags generates all the tags and already defines a extensive and
 381  working header, setting paragraph styles and formatting. This is the
 382  hard part.
 383<P></P>
 384  <B>Author's note:</B>
 385  My entire portuguese <A HREF="http://guia-er.sf.net">regular expression's book</A>
 386  was written in VI, then converted to PageMaker with txt2tags and went to
 387  the publisher. It works :)
 388<P></P>
 389<DT><B>rtf</B></DT><DD>
 390  RTF document
 391<P></P>
 392<DT><B><A HREF="http://en.wikipedia.org/wiki/SGML">SGML</A></B></DT><DD>
 393  It is a common document format which has powerful conversion applications
 394  (<A HREF="http://packages.debian.org/linuxdoc-tools">linuxdoc-tools</A>). From a
 395  single SGML file you can generate HTML, PDF, PostScript, Info, LaTeX, LyX, RTF
 396  and XML documents. The tools also does automatic TOC and break
 397  sections into subpages.
 398<P></P>
 399  Txt2tags generates SGML files in the LinuxDoc system type, ready to
 400  be converted with linuxdoc-tools without any extra catalog files or any
 401  SGML annoying requirements.
 402<P></P>
 403<DT><B><A HREF="http://en.wikipedia.org/wiki/LaTeX">LATEX</A></B></DT><DD>
 404  The preferred academic document format, it is more powerful than you
 405  ever wondered. Full books, complicated formulas and any complex text
 406  can be written in LaTeX. But prepare to loose your hair when you try
 407  to write the tags by hand...
 408<P></P>
 409  Txt2tags generates ready-to-use LaTeX files, doing all the complex
 410  escaping tricks and exceptions. The writer just need to worry about
 411  the text.
 412<P></P>
 413<DT><B>texs</B></DT><DD>
 414  LaTeX Spreadsheet
 415</DL>
 416
 417<H3>Text</H3>
 418
 419<DL>
 420<DT><B>aap</B></DT><DD>
 421  ASCII Art Presentation
 422<P></P>
 423<DT><B>aas</B></DT><DD>
 424  ASCII Art Spreadsheet
 425<P></P>
 426<DT><B>aat</B></DT><DD>
 427  ASCII Art Text
 428<P></P>
 429<DT><B>MAN</B></DT><DD>
 430  UNIX man pages resist over the years. Document formats come and go,
 431  and there they are, unbeatable.
 432<P></P>
 433  There are other tools to generate man documents, but txt2tags has
 434  one advantage: one source, multi targets. So the same man page
 435  contents can be converted to an HTML page, Wiki document and plain text.
 436<P></P>
 437<DT><B>TXT</B></DT><DD>
 438  TXT is text. Simple, pure, beautiful.
 439<P></P>
 440  Although txt2tags marks are very intuitive and discrete, you can remove
 441  them by converting the file to pure TXT.
 442<P></P>
 443  The titles are underlined, and the text is basically left as is on the
 444  source.
 445</DL>
 446
 447<P>
 448Tip: Use the <CODE>--targets</CODE> command line option to get a complete list of
 449all the available targets.
 450</P>
 451
 452<A NAME="struct-support"></A>
 453<H2>Status of Supported Structures by Target</H2>
 454
 455<TABLE ALIGN="center" BORDER="1">
 456<TR>
 457<TH>Structure</TH>
 458<TH>html</TH>
 459<TH>xhtml</TH>
 460<TH>sgml</TH>
 461<TH>dbk</TH>
 462<TH>tex</TH>
 463<TH>lout</TH>
 464<TH>man</TH>
 465<TH>mgp</TH>
 466<TH>creole</TH>
 467<TH>wiki</TH>
 468<TH>gwiki</TH>
 469<TH>pmw</TH>
 470<TH>doku</TH>
 471<TH>moin</TH>
 472<TH>pm6</TH>
 473<TH>adoc</TH>
 474<TH>art</TH>
 475<TH>txt</TH>
 476<TH>tml</TH>
 477</TR>
 478<TR>
 479<TD>headers</TD>
 480<TD ALIGN="center">Y</TD>
 481<TD ALIGN="center">Y</TD>
 482<TD ALIGN="center">Y</TD>
 483<TD ALIGN="center">Y</TD>
 484<TD ALIGN="center">Y</TD>
 485<TD ALIGN="center">Y</TD>
 486<TD ALIGN="center">Y</TD>
 487<TD ALIGN="center">Y</TD>
 488<TD ALIGN="center">-</TD>
 489<TD ALIGN="center">-</TD>
 490<TD ALIGN="center">-</TD>
 491<TD ALIGN="center">Y</TD>
 492<TD ALIGN="center">-</TD>
 493<TD ALIGN="center">-</TD>
 494<TD ALIGN="center">N</TD>
 495<TD ALIGN="center">-</TD>
 496<TD ALIGN="center">Y</TD>
 497<TD ALIGN="center">Y</TD>
 498<TD ALIGN="center">Y</TD>
 499</TR>
 500<TR>
 501<TD>section title</TD>
 502<TD ALIGN="center">Y</TD>
 503<TD ALIGN="center">Y</TD>
 504<TD ALIGN="center">Y</TD>
 505<TD ALIGN="center">Y</TD>
 506<TD ALIGN="center">Y</TD>
 507<TD ALIGN="center">Y</TD>
 508<TD ALIGN="center">Y</TD>
 509<TD ALIGN="center">Y</TD>
 510<TD ALIGN="center">Y</TD>
 511<TD ALIGN="center">Y</TD>
 512<TD ALIGN="center">Y</TD>
 513<TD ALIGN="center">Y</TD>
 514<TD ALIGN="center">Y</TD>
 515<TD ALIGN="center">Y</TD>
 516<TD ALIGN="center">Y</TD>
 517<TD ALIGN="center">Y</TD>
 518<TD ALIGN="center">Y</TD>
 519<TD ALIGN="center">Y</TD>
 520<TD ALIGN="center">Y</TD>
 521</TR>
 522<TR>
 523<TD>paragraphs</TD>
 524<TD ALIGN="center">Y</TD>
 525<TD ALIGN="center">Y</TD>
 526<TD ALIGN="center">Y</TD>
 527<TD ALIGN="center">Y</TD>
 528<TD ALIGN="center">Y</TD>
 529<TD ALIGN="center">Y</TD>
 530<TD ALIGN="center">Y</TD>
 531<TD ALIGN="center">Y</TD>
 532<TD ALIGN="center">Y</TD>
 533<TD ALIGN="center">Y</TD>
 534<TD ALIGN="center">Y</TD>
 535<TD ALIGN="center">Y</TD>
 536<TD ALIGN="center">Y</TD>
 537<TD ALIGN="center">Y</TD>
 538<TD ALIGN="center">Y</TD>
 539<TD ALIGN="center">Y</TD>
 540<TD ALIGN="center">Y</TD>
 541<TD ALIGN="center">Y</TD>
 542<TD ALIGN="center">Y</TD>
 543</TR>
 544<TR>
 545<TD>bold</TD>
 546<TD ALIGN="center">Y</TD>
 547<TD ALIGN="center">Y</TD>
 548<TD ALIGN="center">Y</TD>
 549<TD ALIGN="center">Y</TD>
 550<TD ALIGN="center">Y</TD>
 551<TD ALIGN="center">Y</TD>
 552<TD ALIGN="center">Y</TD>
 553<TD ALIGN="center">Y</TD>
 554<TD ALIGN="center">Y</TD>
 555<TD ALIGN="center">Y</TD>
 556<TD ALIGN="center">Y</TD>
 557<TD ALIGN="center">Y</TD>
 558<TD ALIGN="center">Y</TD>
 559<TD ALIGN="center">Y</TD>
 560<TD ALIGN="center">Y</TD>
 561<TD ALIGN="center">Y</TD>
 562<TD ALIGN="center">-</TD>
 563<TD ALIGN="center">-</TD>
 564<TD ALIGN="center">Y</TD>
 565</TR>
 566<TR>
 567<TD>italic</TD>
 568<TD ALIGN="center">Y</TD>
 569<TD ALIGN="center">Y</TD>
 570<TD ALIGN="center">Y</TD>
 571<TD ALIGN="center">Y</TD>
 572<TD ALIGN="center">Y</TD>
 573<TD ALIGN="center">Y</TD>
 574<TD ALIGN="center">Y</TD>
 575<TD ALIGN="center">Y</TD>
 576<TD ALIGN="center">Y</TD>
 577<TD ALIGN="center">Y</TD>
 578<TD ALIGN="center">Y</TD>
 579<TD ALIGN="center">Y</TD>
 580<TD ALIGN="center">Y</TD>
 581<TD ALIGN="center">Y</TD>
 582<TD ALIGN="center">Y</TD>
 583<TD ALIGN="center">Y</TD>
 584<TD ALIGN="center">-</TD>
 585<TD ALIGN="center">-</TD>
 586<TD ALIGN="center">Y</TD>
 587</TR>
 588<TR>
 589<TD>underline</TD>
 590<TD ALIGN="center">Y</TD>
 591<TD ALIGN="center">Y</TD>
 592<TD ALIGN="center">-</TD>
 593<TD ALIGN="center">Y</TD>
 594<TD ALIGN="center">Y</TD>
 595<TD ALIGN="center">Y</TD>
 596<TD ALIGN="center">-</TD>
 597<TD ALIGN="center">Y</TD>
 598<TD ALIGN="center">-</TD>
 599<TD ALIGN="center">Y</TD>
 600<TD ALIGN="center">-</TD>
 601<TD ALIGN="center">Y</TD>
 602<TD ALIGN="center">Y</TD>
 603<TD ALIGN="center">Y</TD>
 604<TD ALIGN="center">Y</TD>
 605<TD ALIGN="center">N</TD>
 606<TD ALIGN="center">-</TD>
 607<TD ALIGN="center">-</TD>
 608<TD ALIGN="center">Y</TD>
 609</TR>
 610<TR>
 611<TD>strike</TD>
 612<TD ALIGN="center">Y</TD>
 613<TD ALIGN="center">Y</TD>
 614<TD ALIGN="center">N</TD>
 615<TD ALIGN="center">N</TD>
 616<TD ALIGN="center">Y</TD>
 617<TD ALIGN="center">-</TD>
 618<TD ALIGN="center">-</TD>
 619<TD ALIGN="center">-</TD>
 620<TD ALIGN="center">-</TD>
 621<TD ALIGN="center">Y</TD>
 622<TD ALIGN="center">Y</TD>
 623<TD ALIGN="center">Y</TD>
 624<TD ALIGN="center">Y</TD>
 625<TD ALIGN="center">Y</TD>
 626<TD ALIGN="center">N</TD>
 627<TD ALIGN="center">N</TD>
 628<TD ALIGN="center">-</TD>
 629<TD ALIGN="center">-</TD>
 630<TD ALIGN="center">Y</TD>
 631</TR>
 632<TR>
 633<TD>monospaced font</TD>
 634<TD ALIGN="center">Y</TD>
 635<TD ALIGN="center">Y</TD>
 636<TD ALIGN="center">Y</TD>
 637<TD ALIGN="center">Y</TD>
 638<TD ALIGN="center">Y</TD>
 639<TD ALIGN="center">Y</TD>
 640<TD ALIGN="center">-</TD>
 641<TD ALIGN="center">Y</TD>
 642<TD ALIGN="center">-</TD>
 643<TD ALIGN="center">Y</TD>
 644<TD ALIGN="center">Y</TD>
 645<TD ALIGN="center">Y</TD>
 646<TD ALIGN="center">Y</TD>
 647<TD ALIGN="center">Y</TD>
 648<TD ALIGN="center">Y</TD>
 649<TD ALIGN="center">Y</TD>
 650<TD ALIGN="center">-</TD>
 651<TD ALIGN="center">-</TD>
 652<TD ALIGN="center">Y</TD>
 653</TR>
 654<TR>
 655<TD>verbatim line</TD>
 656<TD ALIGN="center">Y</TD>
 657<TD ALIGN="center">Y</TD>
 658<TD ALIGN="center">Y</TD>
 659<TD ALIGN="center">Y</TD>
 660<TD ALIGN="center">Y</TD>
 661<TD ALIGN="center">Y</TD>
 662<TD ALIGN="center">Y</TD>
 663<TD ALIGN="center">Y</TD>
 664<TD ALIGN="center">Y</TD>
 665<TD ALIGN="center">Y</TD>
 666<TD ALIGN="center">Y</TD>
 667<TD ALIGN="center">Y</TD>
 668<TD ALIGN="center">Y</TD>
 669<TD ALIGN="center">Y</TD>
 670<TD ALIGN="center">Y</TD>
 671<TD ALIGN="center">Y</TD>
 672<TD ALIGN="center">-</TD>
 673<TD ALIGN="center">-</TD>
 674<TD ALIGN="center">-</TD>
 675</TR>
 676<TR>
 677<TD>verbatim area</TD>
 678<TD ALIGN="center">Y</TD>
 679<TD ALIGN="center">Y</TD>
 680<TD ALIGN="center">Y</TD>
 681<TD ALIGN="center">Y</TD>
 682<TD ALIGN="center">Y</TD>
 683<TD ALIGN="center">Y</TD>
 684<TD ALIGN="center">Y</TD>
 685<TD ALIGN="center">Y</TD>
 686<TD ALIGN="center">Y</TD>
 687<TD ALIGN="center">Y</TD>
 688<TD ALIGN="center">Y</TD>
 689<TD ALIGN="center">Y</TD>
 690<TD ALIGN="center">Y</TD>
 691<TD ALIGN="center">Y</TD>
 692<TD ALIGN="center">Y</TD>
 693<TD ALIGN="center">Y</TD>
 694<TD ALIGN="center">-</TD>
 695<TD ALIGN="center">-</TD>
 696<TD ALIGN="center">Y</TD>
 697</TR>
 698<TR>
 699<TD>quoted area</TD>
 700<TD ALIGN="center">Y</TD>
 701<TD ALIGN="center">Y</TD>
 702<TD ALIGN="center">Y</TD>
 703<TD ALIGN="center">Y</TD>
 704<TD ALIGN="center">Y</TD>
 705<TD ALIGN="center">Y</TD>
 706<TD ALIGN="center">Y</TD>
 707<TD ALIGN="center">Y</TD>
 708<TD ALIGN="center">Y</TD>
 709<TD ALIGN="center">Y</TD>
 710<TD ALIGN="center">Y</TD>
 711<TD ALIGN="center">Y</TD>
 712<TD ALIGN="center">Y</TD>
 713<TD ALIGN="center">Y</TD>
 714<TD ALIGN="center">Y</TD>
 715<TD ALIGN="center">N</TD>
 716<TD ALIGN="center">Y</TD>
 717<TD ALIGN="center">Y</TD>
 718<TD ALIGN="center">-</TD>
 719</TR>
 720<TR>
 721<TD>internet links</TD>
 722<TD ALIGN="center">Y</TD>
 723<TD ALIGN="center">Y</TD>
 724<TD ALIGN="center">Y</TD>
 725<TD ALIGN="center">Y</TD>
 726<TD ALIGN="center">-</TD>
 727<TD ALIGN="center">-</TD>
 728<TD ALIGN="center">-</TD>
 729<TD ALIGN="center">-</TD>
 730<TD ALIGN="center">Y</TD>
 731<TD ALIGN="center">Y</TD>
 732<TD ALIGN="center">Y</TD>
 733<TD ALIGN="center">Y</TD>
 734<TD ALIGN="center">Y</TD>
 735<TD ALIGN="center">Y</TD>
 736<TD ALIGN="center">-</TD>
 737<TD ALIGN="center">Y</TD>
 738<TD ALIGN="center">-</TD>
 739<TD ALIGN="center">-</TD>
 740<TD ALIGN="center">Y</TD>
 741</TR>
 742<TR>
 743<TD>e-mail links</TD>
 744<TD ALIGN="center">Y</TD>
 745<TD ALIGN="center">Y</TD>
 746<TD ALIGN="center">Y</TD>
 747<TD ALIGN="center">Y</TD>
 748<TD ALIGN="center">-</TD>
 749<TD ALIGN="center">-</TD>
 750<TD ALIGN="center">-</TD>
 751<TD ALIGN="center">-</TD>
 752<TD ALIGN="center">Y</TD>
 753<TD ALIGN="center">Y</TD>
 754<TD ALIGN="center">Y</TD>
 755<TD ALIGN="center">Y</TD>
 756<TD ALIGN="center">Y</TD>
 757<TD ALIGN="center">Y</TD>
 758<TD ALIGN="center">-</TD>
 759<TD ALIGN="center">Y</TD>
 760<TD ALIGN="center">-</TD>
 761<TD ALIGN="center">-</TD>
 762<TD ALIGN="center">Y</TD>
 763</TR>
 764<TR>
 765<TD>local links</TD>
 766<TD ALIGN="center">Y</TD>
 767<TD ALIGN="center">Y</TD>
 768<TD ALIGN="center">Y</TD>
 769<TD ALIGN="center">Y</TD>
 770<TD ALIGN="center">N</TD>
 771<TD ALIGN="center">N</TD>
 772<TD ALIGN="center">-</TD>
 773<TD ALIGN="center">-</TD>
 774<TD ALIGN="center">N</TD>
 775<TD ALIGN="center">N</TD>
 776<TD ALIGN="center">N</TD>
 777<TD ALIGN="center">Y</TD>
 778<TD ALIGN="center">Y</TD>
 779<TD ALIGN="center">Y</TD>
 780<TD ALIGN="center">-</TD>
 781<TD ALIGN="center">N</TD>
 782<TD ALIGN="center">-</TD>
 783<TD ALIGN="center">-</TD>
 784<TD ALIGN="center">Y</TD>
 785</TR>
 786<TR>
 787<TD>named links</TD>
 788<TD ALIGN="center">Y</TD>
 789<TD ALIGN="center">Y</TD>
 790<TD ALIGN="center">Y</TD>
 791<TD ALIGN="center">Y</TD>
 792<TD ALIGN="center">-</TD>
 793<TD ALIGN="center">-</TD>
 794<TD ALIGN="center">-</TD>
 795<TD ALIGN="center">-</TD>
 796<TD ALIGN="center">Y</TD>
 797<TD ALIGN="center">Y</TD>
 798<TD ALIGN="center">Y</TD>
 799<TD ALIGN="center">Y</TD>
 800<TD ALIGN="center">Y</TD>
 801<TD ALIGN="center">Y</TD>
 802<TD ALIGN="center">-</TD>
 803<TD ALIGN="center">Y</TD>
 804<TD ALIGN="center">-</TD>
 805<TD ALIGN="center">-</TD>
 806<TD ALIGN="center">Y</TD>
 807</TR>
 808<TR>
 809<TD>bulleted list</TD>
 810<TD ALIGN="center">Y</TD>
 811<TD ALIGN="center">Y</TD>
 812<TD ALIGN="center">Y</TD>
 813<TD ALIGN="center">Y</TD>
 814<TD ALIGN="center">Y</TD>
 815<TD ALIGN="center">Y</TD>
 816<TD ALIGN="center">Y</TD>
 817<TD ALIGN="center">Y</TD>
 818<TD ALIGN="center">Y</TD>
 819<TD ALIGN="center">Y</TD>
 820<TD ALIGN="center">Y</TD>
 821<TD ALIGN="center">Y</TD>
 822<TD ALIGN="center">Y</TD>
 823<TD ALIGN="center">Y</TD>
 824<TD ALIGN="center">Y</TD>
 825<TD ALIGN="center">Y</TD>
 826<TD ALIGN="center">Y</TD>
 827<TD ALIGN="center">Y</TD>
 828<TD ALIGN="center">Y</TD>
 829</TR>
 830<TR>
 831<TD>numbered list</TD>
 832<TD ALIGN="center">Y</TD>
 833<TD ALIGN="center">Y</TD>
 834<TD ALIGN="center">Y</TD>
 835<TD ALIGN="center">Y</TD>
 836<TD ALIGN="center">Y</TD>
 837<TD ALIGN="center">Y</TD>
 838<TD ALIGN="center">Y</TD>
 839<TD ALIGN="center">Y</TD>
 840<TD ALIGN="center">Y</TD>
 841<TD ALIGN="center">Y</TD>
 842<TD ALIGN="center">Y</TD>
 843<TD ALIGN="center">Y</TD>
 844<TD ALIGN="center">Y</TD>
 845<TD ALIGN="center">Y</TD>
 846<TD ALIGN="center">Y</TD>
 847<TD ALIGN="center">Y</TD>
 848<TD ALIGN="center">Y</TD>
 849<TD ALIGN="center">Y</TD>
 850<TD ALIGN="center">Y</TD>
 851</TR>
 852<TR>
 853<TD>definition list</TD>
 854<TD ALIGN="center">Y</TD>
 855<TD ALIGN="center">Y</TD>
 856<TD ALIGN="center">Y</TD>
 857<TD ALIGN="center">Y</TD>
 858<TD ALIGN="center">Y</TD>
 859<TD ALIGN="center">Y</TD>
 860<TD ALIGN="center">Y</TD>
 861<TD ALIGN="center">N</TD>
 862<TD ALIGN="center">Y</TD>
 863<TD ALIGN="center">Y</TD>
 864<TD ALIGN="center">-</TD>
 865<TD ALIGN="center">Y</TD>
 866<TD ALIGN="center">-</TD>
 867<TD ALIGN="center">Y</TD>
 868<TD ALIGN="center">N</TD>
 869<TD ALIGN="center">N</TD>
 870<TD ALIGN="center">Y</TD>
 871<TD ALIGN="center">Y</TD>
 872<TD ALIGN="center">Y</TD>
 873</TR>
 874<TR>
 875<TD>horizontal line</TD>
 876<TD ALIGN="center">Y</TD>
 877<TD ALIGN="center">Y</TD>
 878<TD ALIGN="center">-</TD>
 879<TD ALIGN="center">N</TD>
 880<TD ALIGN="center">Y</TD>
 881<TD ALIGN="center">Y</TD>
 882<TD ALIGN="center">-</TD>
 883<TD ALIGN="center">Y</TD>
 884<TD ALIGN="center">Y</TD>
 885<TD ALIGN="center">Y</TD>
 886<TD ALIGN="center">-</TD>
 887<TD ALIGN="center">Y</TD>
 888<TD ALIGN="center">Y</TD>
 889<TD ALIGN="center">Y</TD>
 890<TD ALIGN="center">N</TD>
 891<TD ALIGN="center">N</TD>
 892<TD ALIGN="center">Y</TD>
 893<TD ALIGN="center">Y</TD>
 894<TD ALIGN="center">Y</TD>
 895</TR>
 896<TR>
 897<TD>image</TD>
 898<TD ALIGN="center">Y</TD>
 899<TD ALIGN="center">Y</TD>
 900<TD ALIGN="center">Y</TD>
 901<TD ALIGN="center">Y</TD>
 902<TD ALIGN="center">Y</TD>
 903<TD ALIGN="center">Y</TD>
 904<TD ALIGN="center">-</TD>
 905<TD ALIGN="center">Y</TD>
 906<TD ALIGN="center">Y</TD>
 907<TD ALIGN="center">Y</TD>
 908<TD ALIGN="center">Y</TD>
 909<TD ALIGN="center">Y</TD>
 910<TD ALIGN="center">Y</TD>
 911<TD ALIGN="center">Y</TD>
 912<TD ALIGN="center">N</TD>
 913<TD ALIGN="center">Y</TD>
 914<TD ALIGN="center">-</TD>
 915<TD ALIGN="center">-</TD>
 916<TD ALIGN="center">Y</TD>
 917</TR>
 918<TR>
 919<TD>table</TD>
 920<TD ALIGN="center">Y</TD>
 921<TD ALIGN="center">Y</TD>
 922<TD ALIGN="center">Y</TD>
 923<TD ALIGN="center">N</TD>
 924<TD ALIGN="center">Y</TD>
 925<TD ALIGN="center">N</TD>
 926<TD ALIGN="center">Y</TD>
 927<TD ALIGN="center">N</TD>
 928<TD ALIGN="center">Y</TD>
 929<TD ALIGN="center">Y</TD>
 930<TD ALIGN="center">Y</TD>
 931<TD ALIGN="center">Y</TD>
 932<TD ALIGN="center">Y</TD>
 933<TD ALIGN="center">Y</TD>
 934<TD ALIGN="center">N</TD>
 935<TD ALIGN="center">N</TD>
 936<TD ALIGN="center">N</TD>
 937<TD ALIGN="center">N</TD>
 938<TD ALIGN="center">Y</TD>
 939</TR>
 940<TR>
 941<TH>Extras</TH>
 942<TH>html</TH>
 943<TH>xhtml</TH>
 944<TH>sgml</TH>
 945<TH>dbk</TH>
 946<TH>tex</TH>
 947<TH>lout</TH>
 948<TH>man</TH>
 949<TH>mgp</TH>
 950<TH>creole</TH>
 951<TH>wiki</TH>
 952<TH>gwiki</TH>
 953<TH>pmw</TH>
 954<TH>doku</TH>
 955<TH>moin</TH>
 956<TH>pm6</TH>
 957<TH>adoc</TH>
 958<TH>art</TH>
 959<TH>txt</TH>
 960<TH>Y</TH>
 961</TR>
 962<TR>
 963<TD>image align</TD>
 964<TD ALIGN="center">Y</TD>
 965<TD ALIGN="center">Y</TD>
 966<TD ALIGN="center">N</TD>
 967<TD ALIGN="center">N</TD>
 968<TD ALIGN="center">N</TD>
 969<TD ALIGN="center">Y</TD>
 970<TD ALIGN="center">-</TD>
 971<TD ALIGN="center">Y</TD>
 972<TD ALIGN="center">N</TD>
 973<TD ALIGN="center">Y</TD>
 974<TD ALIGN="center">-</TD>
 975<TD ALIGN="center">N</TD>
 976<TD ALIGN="center">Y</TD>
 977<TD ALIGN="center">N</TD>
 978<TD ALIGN="center">N</TD>
 979<TD ALIGN="center">N</TD>
 980<TD ALIGN="center">-</TD>
 981<TD ALIGN="center">-</TD>
 982<TD ALIGN="center">Y</TD>
 983</TR>
 984<TR>
 985<TD>table cell align</TD>
 986<TD ALIGN="center">Y</TD>
 987<TD ALIGN="center">Y</TD>
 988<TD ALIGN="center">Y</TD>
 989<TD ALIGN="center">N</TD>
 990<TD ALIGN="center">Y</TD>
 991<TD ALIGN="center">N</TD>
 992<TD ALIGN="center">Y</TD>
 993<TD ALIGN="center">N</TD>
 994<TD ALIGN="center">N</TD>
 995<TD ALIGN="center">N</TD>
 996<TD ALIGN="center">-</TD>
 997<TD ALIGN="center">N</TD>
 998<TD ALIGN="center">-</TD>
 999<TD ALIGN="center">Y</TD>
1000<TD ALIGN="center">N</TD>
1001<TD ALIGN="center">N</TD>
1002<TD ALIGN="center">N</TD>
1003<TD ALIGN="center">N</TD>
1004<TD ALIGN="center">Y</TD>
1005</TR>
1006<TR>
1007<TD>table column span</TD>
1008<TD ALIGN="center">Y</TD>
1009<TD ALIGN="center">Y</TD>
1010<TD ALIGN="center">N</TD>
1011<TD ALIGN="center">N</TD>
1012<TD ALIGN="center">Y</TD>
1013<TD ALIGN="center">N</TD>
1014<TD ALIGN="center">N</TD>
1015<TD ALIGN="center">N</TD>
1016<TD ALIGN="center">N</TD>
1017<TD ALIGN="center">N</TD>
1018<TD ALIGN="center">-</TD>
1019<TD ALIGN="center">N</TD>
1020<TD ALIGN="center">-</TD>
1021<TD ALIGN="center">N</TD>
1022<TD ALIGN="center">N</TD>
1023<TD ALIGN="center">N</TD>
1024<TD ALIGN="center">N</TD>
1025<TD ALIGN="center">N</TD>
1026<TD ALIGN="center">Y</TD>
1027</TR>
1028</TABLE>
1029
1030<TABLE ALIGN="center">
1031<TR>
1032<TH></TH>
1033<TH>Legend</TH>
1034</TR>
1035<TR>
1036<TD><B>Y</B></TD>
1037<TD><I>Supported</I></TD>
1038</TR>
1039<TR>
1040<TD><B>N</B></TD>
1041<TD><I>Not supported (may be in future releases)</I></TD>
1042</TR>
1043<TR>
1044<TD><B>-</B></TD>
1045<TD><I>Not supported (can't be done on this target)</I></TD>
1046</TR>
1047</TABLE>
1048
1049<A NAME="interfaces"></A>
1050<H2>The Three User Interfaces: Gui, Web and Command Line</H2>
1051
1052<P>
1053As different users have different needs and environments, txt2tags is
1054very flexible on how it runs.
1055</P>
1056<P>
1057There are three User Interfaces for the program, each one with its own
1058purpose and features.
1059</P>
1060
1061<UL>
1062<LI><B>Gui</B>: Written in Tk, brings the windowing and clicking to txt2tags.
1063<LI><B>Web</B>: Written in PHP, allows users to run txt2tags on the browser,
1064           requiring no installation on the client side.
1065<LI><B>Command Line</B>: Written in Python, it's the program core. All
1066           features are available as command line options.
1067</UL>
1068
1069<A NAME="gui"></A>
1070<H3>Graphical Interface</H3>
1071
1072<P>
1073Since version 1.0, there is a nice Graphical Interface, that works on
1074Linux, Windows, Mac and others. Just call txt2tags with the <CODE>--gui</CODE>
1075option to open it.
1076</P>
1077<P>
1078The interface is pretty simple and intuitive:
1079</P>
1080                     <center><IMG ALIGN="middle" SRC="./gui.png" BORDER="0" ALT=""></center>  
1081
1082<OL>
1083<LI>You locate the source .t2t file on the disk and its options are
1084  loaded.
1085<P></P>
1086<LI>If the target is still empty, you must choose one.
1087<P></P>
1088<LI>Then there are some options you may choose, but none of them are
1089  required.
1090<P></P>
1091<LI>Finally, press the "Convert!" button.
1092</OL>
1093
1094<P>
1095A nice option is the "<I>Dump to screen</I>", so you can check
1096the resulting code on a separate window, no file is saved at all. When
1097the code is OK, you uncheck it and the file will be saved.
1098</P>
1099<P>
1100The default interface colors can be changed on the <A HREF="#rc">configuration file</A>,
1101using the <CODE>%!guicolors</CODE> settings. For example:
1102</P>
1103
1104<PRE>
1105% set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
1106%!guicolors: blue white brown yellow
1107</PRE>
1108
1109<H3>Web Interface</H3>
1110
1111<P>
1112The Web Interface is up and running on the Internet at
1113<A HREF="http://txt2tags.org/online.php">http://txt2tags.org/online.php</A>, so you can use and test the program
1114instantly, before download.
1115</P>
1116          <center><IMG ALIGN="middle" SRC="./web.png" BORDER="0" ALT=""></center>  
1117<P>
1118One can also put this interface on the local intranet avoiding to
1119install txt2tags in all machines.
1120</P>
1121
1122<A NAME="cmdline"></A>
1123<H3>Command Line Interface</H3>
1124
1125<P>
1126For command line power users, the --help should be enough:
1127</P>
1128
1129<PRE>
1130Usage: txt2tags [OPTIONS] [infile.t2t ...]
1131
1132      --targets       print a list of all the available targets and exit
1133  -t, --target=TYPE   set target document type. currently supported:
1134                      adoc, art, creole, dbk, doku, gwiki, html, lout, man,
1135                      mgp, moin, pm6, pmw, sgml, tex, txt, wiki, xhtml
1136  -i, --infile=FILE   set FILE as the input file name ('-' for STDIN)
1137  -o, --outfile=FILE  set FILE as the output file name ('-' for STDOUT)
1138      --encoding=ENC  set target file encoding (utf-8, iso-8859-1, etc)
1139      --toc           add an automatic Table of Contents to the output
1140      --toc-level=N   set maximum TOC level (depth) to N
1141      --toc-only      print the Table of Contents and exit
1142  -n, --enum-title    enumerate all titles as 1, 1.1, 1.1.1, etc
1143      --style=FILE    use FILE as the document style (like HTML CSS)
1144      --css-sugar     insert CSS-friendly tags for HTML/XHTML
1145      --css-inside    insert CSS file contents inside HTML/XHTML headers
1146  -H, --no-headers    suppress header and footer from the output
1147      --mask-email    hide email from spam robots. x@y.z turns &lt;x (a) y z&gt;
1148      --slides        format output as presentation slides (used by -t art)
1149      --width=N       set the output's width to N columns (used by -t art)
1150      --height=N      set the output's height to N rows (used by -t art)
1151  -C, --config-file=F read configuration from file F
1152      --gui           invoke Graphical Tk Interface
1153  -q, --quiet         quiet mode, suppress all output (except errors)
1154  -v, --verbose       print informative messages during conversion
1155  -h, --help          print this help information and exit
1156  -V, --version       print program version and exit
1157      --dump-config   print all the configuration found and exit
1158      --dump-source   print the document source, with includes expanded
1159
1160Turn OFF options:
1161     --no-css-inside, --no-css-sugar, --no-dump-config, --no-dump-source,
1162     --no-encoding, --no-enum-title, --no-headers, --no-infile,
1163     --no-mask-email, --no-outfile, --no-quiet, --no-rc, --no-slides,
1164     --no-style, --no-targets, --no-toc, --no-toc-only
1165
1166Example:
1167     txt2tags -t html --toc file.t2t
1168
1169By default, converted output is saved to 'infile.&lt;target&gt;'.
1170Use --outfile to force an output file name.
1171If  input file is '-', reads from STDIN.
1172If output file is '-', dumps output to STDOUT.
1173</PRE>
1174
1175<P>
1176Please read the txt2tags man page for detailed information about options and command line use.
1177</P>
1178<P>
1179Examples:
1180</P>
1181
1182<TABLE>
1183<TR>
1184<TD><B>Convert to HTML</B></TD>
1185<TD><CODE>$ txt2tags -t html file.t2t</CODE></TD>
1186</TR>
1187<TR>
1188<TD><B>The same, using redirection</B></TD>
1189<TD><CODE>$ txt2tags -t html -o - file.t2t &gt; file.html</CODE></TD>
1190</TR>
1191<TR>
1192<TD></TD>
1193<TD>.</TD>
1194</TR>
1195<TR>
1196<TD><B>Including Table Of Contents</B></TD>
1197<TD><CODE>$ txt2tags -t html --toc file.t2t</CODE></TD>
1198</TR>
1199<TR>
1200<TD><B>And also, numbering titles</B></TD>
1201<TD><CODE>$ txt2tags -t html --toc --enum-title file.t2t</CODE></TD>
1202</TR>
1203<TR>
1204<TD></TD>
1205<TD>.</TD>
1206</TR>
1207<TR>
1208<TD><B>Contents quick view</B></TD>
1209<TD><CODE>$ txt2tags --toc-only file.t2t</CODE></TD>
1210</TR>
1211<TR>
1212<TD><B>Maybe enumerate them?</B></TD>
1213<TD><CODE>$ txt2tags --toc-only --enum-title file.t2t</CODE></TD>
1214</TR>
1215<TR>
1216<TD></TD>
1217<TD>.</TD>
1218</TR>
1219<TR>
1220<TD><B>One liners from STDIN</B></TD>
1221<TD><CODE>$ echo -e "\n**bold**" | txt2tags -t html --no-headers -</CODE></TD>
1222</TR>
1223<TR>
1224<TD><B>Testing Mask Email feature</B></TD>
1225<TD><CODE>$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -</CODE></TD>
1226</TR>
1227</TABLE>
1228
1229<A NAME="install"></A>
1230<H1>Part II - Install</H1>
1231
1232<P>
1233Just download the program and run it on your machine.
1234</P>
1235
1236<A NAME="download-python"></A>
1237<H2>Download &amp; Install Python</H2>
1238
1239<P>
1240First of all, you must download and install <A HREF="http://www.python.org">Python</A> on
1241your system. Txt2tags requires Python version 2.2 or newer.
1242</P>
1243<P>
1244Note that Python is already installed by default in Linux and Mac systems. If you're using those, you're done, just skip this step.
1245</P>
1246<P>
1247If you are not sure if you have Python or not, open a console (tty,
1248xterm, MSDOS, Terminal.app) and type <CODE>python</CODE>. If it is not installed, the system
1249will tell you.
1250</P>
1251
1252<A NAME="download-txt2tags"></A>
1253<H2>Download txt2tags</H2>
1254
1255<P>
1256The official location for txt2tags distribution is on the program
1257site, at <A HREF="http://txt2tags.org">http://txt2tags.org</A>. Just download and uncompress the package (.tgz file).
1258</P>
1259<P>
1260If you're in Linux, you can also use the automatic installer of your system. Some examples:
1261</P>
1262
1263<UL>
1264<LI>yum install txt2tags
1265<LI>sudo apt-get install txt2tags
1266</UL>
1267
1268<A NAME="install-txt2tags"></A>
1269<H2>Install txt2tags</H2>
1270
1271<P>
1272As a single Python script, txt2tags needs no installation at all.
1273</P>
1274<P>
1275The only file needed to use the program is the txt2tags script. The
1276other files of the package are documentation, tools and sample files.
1277</P>
1278<P>
1279The fail-proof way to run txt2tags, is calling Python with it:
1280</P>
1281
1282<PRE>
1283prompt$ python txt2tags
1284</PRE>
1285
1286<P>
1287If you want to install txt2tags on the system as a stand alone
1288program, just copy the txt2tags script to a system PATH
1289directory and make sure the system knows how to run it.
1290</P>
1291
1292<DL>
1293<DT><B>UNIX/Linux/Mac</B></DT><DD>
1294  Make the script executable (<CODE>chmod +x txt2tags</CODE>) and copy it to a
1295  $PATH directory (<CODE>cp txt2tags /usr/local/bin</CODE>)
1296<P></P>
1297<DT><B>Windows</B></DT><DD>
1298  Rename the script adding the .py extension
1299  and copy it to a system PATH directory, such as <CODE>C:\Windows\System32</CODE>.
1300</DL>
1301
1302<P>
1303After that, you can create an icon on your desktop for it, if you want to
1304use the program's Graphical Interface.
1305</P>
1306
1307<A NAME="editor-syntax"></A>
1308<H2>Install Text Editor Syntax Highlighting File (optional)</H2>
1309
1310<P>
1311Txt2tags comes with handy syntax highlighting files to be used by the
1312following text editors:
1313</P>
1314
1315<UL>
1316<LI>Vim
1317<LI>Emacs
1318<LI>Nano
1319<LI>Kate
1320<LI>Gedit
1321<LI>JOE
1322<LI>le
1323<LI>ne
1324<LI>TextMate
1325</UL>
1326
1327<P>
1328This syntax highlighting files have all the txt2tags rules and marks
1329registered, helping the user to write error-free documents. Showing the
1330marks in colors, you see on-the-fly if you wrote it right.
1331</P>
1332
1333<TABLE ALIGN="center">
1334<TR>
1335<TD ALIGN="center"><center><IMG ALIGN="middle" SRC="./vim.png" BORDER="0" ALT=""></center></TD>
1336</TR>
1337<TR>
1338<TD ALIGN="center">Sample file opened in Vim Editor</TD>
1339</TR>
1340</TABLE>
1341
1342<P>
1343Each editor has a different install procedure for a syntax highlighting
1344file, please read the syntax file headers and the editor documentation.
1345</P>
1346
1347<A NAME="your-1st-doc"></A>
1348<H1>Part III - Writing and Converting Your First Document</H1>
1349
1350<H2>Check the Tools</H2>
1351
1352<P>
1353To make the first conversion you will need three things: txt2tags, a
1354text editor and a web browser.
1355</P>
1356
1357<OL>
1358<LI>Make sure txt2tags is installed and running on your system.
1359<P></P>
1360  <UL>
1361  <LI><B>Command Line Interface:</B> Call "txt2tags" on the command line and
1362    the program should give you a "Missing input file" message. If it is
1363    not working, try <CODE>python /path/to/txt2tags</CODE> or even
1364    <CODE>/path/to/python /path/to/txt2tags</CODE> if Python is not on your PATH.
1365  <P></P>
1366  <LI><B>Gui Interface:</B> Click on the program icon to launch the Gui
1367    Interface or call <CODE>txt2tags --gui</CODE>.
1368  <P></P>
1369  </UL>
1370<LI>Open the text editor your are comfortable with. It can be <B>any</B> text
1371  editor, from the good old VI to MS Word or OpenOffice.org. Create a
1372  brand new empty document to be your first txt2tags one and remember to
1373  save it as plain text.
1374<P></P>
1375<LI>Launch your favorite web browser to see the results of the conversion.
1376</OL>
1377
1378<H2>Write the Document Header</H2>
1379
1380<OL>
1381<LI>Go to the text editor and on the very first line type the document
1382  main title: <I>My First Document</I>
1383<LI>On the second line make a subtitle, inserting this text:
1384  <I>A txt2tags test</I>
1385<LI>Then, on the third line, put some time information:
1386  <I>Sunday, 2004</I>
1387</OL>
1388
1389<P>
1390If everything went right, you should be seeing a three line document
1391with this contents:
1392</P>
1393
1394<PRE>
1395My First Document
1396A txt2tags test
1397Sunday, 2004
1398</PRE>
1399
1400<P>
1401This is just a part of the document, but we can already convert it and
1402check the results.
1403</P>
1404<P>
1405Now save this document with the name <CODE>test.txt</CODE>. Remember to save it
1406as plain text. Pay attention to which folder you are saving the file,
1407you will need to remember it soon.
1408</P>
1409
1410<H2>The First Conversion - Gui Interface</H2>
1411
1412<P>
1413If you are in the Command Line Interface, please skip this step and read
1414the next one.
1415</P>
1416<P>
1417If you are in the Gui Interface, follow this steps:
1418</P>
1419    <center><IMG ALIGN="middle" SRC="./firstdoc.png" BORDER="0" ALT=""></center> 
1420
1421<OL>
1422<LI>Press the "Browse" button and choose the <CODE>test.txt</CODE> you just saved
1423  (remember the folder!).
1424<LI>Back to the first screen, select "HTML page" on the "Target document
1425  type" combo.
1426<LI>Press the "Convert!" button.
1427</OL>
1428
1429   <center><IMG ALIGN="middle" SRC="./firstdoc-done.png" BORDER="0" ALT=""></center> 
1430<P>
1431A dialog box will appear, telling you that the file was converted
1432successfully. Note that the generated HTML page was saved on the same
1433folder as the text file, with the "html" extension.
1434</P>
1435
1436<H2>The First Conversion - Command Line Interface</H2>
1437
1438<P>
1439If you are in the Command Line Interface, move to the folder where the
1440file was saved and type this command:
1441</P>
1442
1443<PRE>
1444txt2tags --target html test.txt
1445</PRE>
1446
1447<P>
1448The option <CODE>--target</CODE> is followed
1449by the "html" string, which tells the program to what format your text
1450file will be converted. The last item is the text filename.
1451</P>
1452<P>
1453The results were saved to the <CODE>test.html</CODE>
1454file and then the program will show you the
1455"<I>txt2tags wrote test.html</I>" message.
1456If some error occurred, read the message carefully.
1457</P>
1458<P>
1459Here is a sample of how it will be shown on your screen:
1460</P>
1461
1462<PRE>
1463prompt$ txt2tags --target html test.txt
1464txt2tags wrote test.html
1465prompt$
1466</PRE>
1467
1468<H2>Check the Results</H2>
1469
1470<P>
1471Open the <CODE>test.html</CODE> file on the web browser to check if everything
1472is ok.
1473</P>
1474   <center><IMG ALIGN="middle" SRC="./firstdoc-html.png" BORDER="0" ALT=""></center> 
1475<P>
1476Here it is! You just typed three simple lines of text and txt2tags made
1477all the work to set the HTML page heading information, text alignment,
1478sizes, spacing and appearance. See that the main title is also placed at the
1479browser title bar.
1480</P>
1481	<BLOCKQUOTE>
1482	You write text, txt2tags does the rest ;)
1483	</BLOCKQUOTE>
1484<P>
1485Tip: You can also use CSS files on HTML pages generated by txt2tags, so the
1486page appearance is 100% configurable.
1487</P>
1488
1489<H2>Writing the Document Body</H2>
1490
1491<P>
1492Now back to the text editor, the next step is to type the document
1493contents. You can write plain text as you normally do on email messages.
1494You will see that txt2tags recognizes paragraphs and list of items
1495automatically, you don't have to "mark" them.
1496</P>
1497<P>
1498Then again: save it, convert and check the results. This is the
1499development cycle of a document in txt2tags. You just focus on the
1500document contents, finishing documents faster than other editors. No
1501mouse clicking, no menus, no windows, no distraction.
1502</P>
1503<P>
1504Considering the following contents for the <CODE>test.txt</CODE> file, which is
1505only plain text, compare the generated HTML page:
1506</P>
1507
1508<PRE>
1509My First Document
1510A txt2tags test
1511Sunday, 2004
1512
1513Well, let's try this txt2tags thing.
1514I don't know what to write.
1515
1516Mmmmmm, I know what I need to do now:
1517- Take a shower
1518- Eat a pizza
1519- Sleep
1520</PRE>
1521
1522   <center><IMG ALIGN="middle" SRC="./firstdoc-fullhtml.png" BORDER="0" ALT=""></center> 
1523<P>
1524You can write a full homepage with 0% of HTML knowledge. You don't need
1525to insert any tags. And more, the same text file can be converted to any
1526of the other txt2tags supported formats.
1527</P>
1528<P>
1529Besides plain text, txt2tags has some very simple marks, that you'll
1530use when you need some other formatting or structures like bold, italic,
1531title, images, table and other. As a quick sample,
1532<CODE>**stars for bold**</CODE> and <CODE>== equals for title ==</CODE>. You can learn the
1533marks on the <A HREF="http://txt2tags.org/markup.html">Txt2tags Markup Demo</A>.
1534</P>
1535
1536<A NAME="concepts"></A>
1537<H1>Part IV - Mastering Txt2tags Concepts</H1>
1538
1539<A NAME="areas"></A>
1540<H2>The .t2t document Areas</H2>
1541
1542<P>
1543Txt2tags marked files are divided in 3 areas. Each area has its own
1544rules and purpose. They are:
1545</P>
1546
1547<DL>
1548<DT><I>Header Area</I></DT><DD>
1549  Place for Document Title, Author, Version and Date information.
1550<DT><I>Config Area</I></DT><DD>
1551  Place for general Document Settings and Parser behavior modifiers.
1552<DT><I>Body Area</I></DT><DD>
1553  Place for the Document Content.
1554</DL>
1555
1556<P>
1557All areas are optional. You can write a txt2tags document with just
1558headers (such as our first example), or a document with no headers or settings.
1559</P>
1560<P>
1561The areas are delimited by special rules, which will be seen in detail
1562on the next chapter. For now, this is a representation of the
1563areas on a document:
1564</P>
1565
1566<PRE>
1567             ____________
1568            |            |
1569            |   HEADERS  |       1. First, the Headers
1570            |            |
1571            |   CONFIG   |       2. Then the Settings
1572            |            |
1573            |    BODY    |       3. And finally the Document Body,
1574            |            |
1575            |    ...     |          which goes until the end
1576            |    ...     |
1577            |____________|
1578
1579</PRE>
1580
1581<P>
1582In short, this is how the areas are defined:
1583</P>
1584
1585<TABLE ALIGN="center">
1586<TR>
1587<TD ALIGN="center"><B>Headers</B></TD>
1588<TD>First 3 lines of the file, or the first line blank for No Headers.</TD>
1589</TR>
1590<TR>
1591<TD ALIGN="center"><B>Config</B></TD>
1592<TD>Begins right after the Header (4th or 2nd line) and ends when the <I>Body Area</I> starts.</TD>
1593</TR>
1594<TR>
1595<TD ALIGN="center"><B>Body</B></TD>
1596<TD>The first valid text line (not comment or setting) after the <I>Header Area</I>.</TD>
1597</TR>
1598</TABLE>
1599
1600<H3>Full Example</H3>
1601
1602<PRE>
1603My nice doc Title
1604Mr. John Doe
1605Last Updated: %%mtime(%c)
1606
1607%!target  : html
1608%!style   : fancy.css
1609%!encoding: UTF-8
1610%!options : --toc --enum-title
1611
1612Hi! This is my test document.
1613Its content will end here.
1614</PRE>
1615
1616<A NAME="headers-area"></A>
1617<H2>Header Area</H2>
1618
1619<P>
1620Location:
1621</P>
1622
1623<UL>
1624<LI>Fixed position: <B>First 3 lines</B> of the file. Period.
1625<LI>Fixed position: <B>First line</B> of the file if it is blank. This
1626  means Empty Headers.
1627</UL>
1628
1629<P>
1630The Header Area is the only one that has a fixed position, line
1631oriented. They are located at the first three lines of the source file.
1632</P>
1633<P>
1634These lines are content-free, with no static information type needed.
1635But the following is recommended:
1636</P>
1637
1638<UL>
1639<LI><I>line 1</I>: document title
1640<LI><I>line 2</I>: author name and/or email
1641<LI><I>line 3</I>: document date and/or version
1642              (nice place for <CODE>%%date</CODE>)
1643</UL>
1644
1645<P>
1646Keep in mind that the first 3 lines of the source document will be the
1647first 3 lines on the target document, separated and with high contrast
1648to the text body (i.e. big letters, bold). If paging is allowed, the
1649headers will be alone and centralized on the first page.
1650</P>
1651
1652<H4>Less (or None) Header lines</H4>
1653
1654<P>
1655Sometimes the user wants to specify less than three lines for headers,
1656giving just the document title and/or date information.
1657</P>
1658<P>
1659Just let the 2nd and/or the 3rd lines empty (blank) and this position
1660will not be placed at the target document. But keep in mind that even
1661blanks, these lines are still part of the headers, so the document body
1662must start <B>after</B> the 3rd line anyway.
1663</P>
1664<P>
1665The title is the only required header (the first line), but if you
1666leave it blank, you are saying that your document has <B>no headers</B>.
1667So the <I>Body Area</I> will begin right after, on the 2nd line.
1668</P>
1669<P>
1670No headers on the document is often useful if you want to specify your
1671own customized headers after converting. The command line option
1672<CODE>--no-headers</CODE> is usually required for this kind of operation.
1673</P>
1674
1675<H4>Straight to the point</H4>
1676
1677<P>
1678In short: <B>"Headers are just <U>positions</U>, not contents"</B>
1679</P>
1680<P>
1681Place one text on the first line, and it will appear on the target's
1682first line. The same for 2nd and 3rd header lines.
1683</P>
1684
1685<A NAME="config-area"></A>
1686<H2>Config Area</H2>
1687
1688<P>
1689Location:
1690</P>
1691
1692<UL>
1693<LI>Begins right after the Header Area
1694  <UL>
1695  <LI>Begins on the <B>4th line</B> of the file if <B>Headers</B> were specified
1696  <LI>Begins on the <B>2nd line</B> of the file if <B>No Headers</B> were specified
1697  </UL>
1698<LI>Ends when the Body Area starts
1699  <UL>
1700  <LI>Ends by a non Setting, Blank or Comment line
1701  </UL>
1702</UL>
1703
1704<P>
1705The Config Area is optional. An average user can write lots of txt2tags
1706files without even know it exists, but the experienced users will
1707enjoy the power and control it provides.
1708</P>
1709<P>
1710The Config Area is used to store document-specific settings, so you don't
1711have to type them on the command line when converting the document. For
1712example, you can set the default document target type and encoding.
1713</P>
1714<P>
1715Please read the <A HREF="#settings-overview">Settings section</A> for more
1716information about them.
1717</P>
1718
1719<A NAME="body-area"></A>
1720<H2>Body Area</H2>
1721
1722<P>
1723Location:
1724</P>
1725
1726<UL>
1727<LI>Begins on the first valid text line of the file
1728  <UL>
1729  <LI>Headers, Settings and Comments are <B>not</B> valid text lines
1730  </UL>
1731<LI>Ends at the end of the file (EOF)
1732</UL>
1733
1734<P>
1735The body is anything outside Headers and Config Areas.
1736</P>
1737<P>
1738The body holds the document contents and all formatting and structures
1739txt2tags can recognize. Inside the body you can also put comments for
1740<I>TODOs</I> and self notes.
1741</P>
1742<P>
1743You can use the <CODE>--no-headers</CODE> command line option to convert only the
1744document body, suppressing the headers. This is useful to set your own
1745headers on a separate file, then join the converted body.
1746</P>
1747
1748<A NAME="settings-overview"></A>
1749<H2>Settings</H2>
1750
1751<P>
1752Settings are special configurations placed at the source document's
1753Config Area that can affect the conversion process. Their syntax is:
1754</P>
1755
1756<PRE>
1757%! keyword : value
1758</PRE>
1759
1760<P>
1761List of valid keywords:
1762</P>
1763
1764<TABLE ALIGN="center" BORDER="1">
1765<TR>
1766<TH>Keyword</TH>
1767<TH>Description</TH>
1768</TR>
1769<TR>
1770<TD ALIGN="center">Target</TD>
1771<TD>Set the default target to the document be converted to.</TD>
1772</TR>
1773<TR>
1774<TD ALIGN="center">Options</TD>
1775<TD>Set the default options to be used on the conversion. The format is the same as the command line options.</TD>
1776</TR>
1777<TR>
1778<TD ALIGN="center">Style</TD>
1779<TD>Set the document style. Used to define a CSS file for HTML/XHTML and to load a package in LaTeX.</TD>
1780</TR>
1781<TR>
1782<TD ALIGN="center">Encoding</TD>
1783<TD>Set the document Character Set. Used if the document contains accented letters or other not-ASCII characters.</TD>
1784</TR>
1785<TR>
1786<TD ALIGN="center">PreProc</TD>
1787<TD>Input filter. Sets "find and replace" rules to be applied on the Body Area of the source document.</TD>
1788</TR>
1789<TR>
1790<TD ALIGN="center">PostProc</TD>
1791<TD>Output filter. Sets "find and replace" rules to be applied on the converted document.</TD>
1792</TR>
1793</TABLE>
1794
1795<P>
1796Example:
1797</P>
1798
1799<PRE>
1800%!target  : html
1801%!options : --toc --toc-level 3
1802%!style   : fancy.css
1803%!encoding: UTF-8
1804%!preproc : "AMJ"        "Aurelio Marinho Jargas"
1805%!postproc: '&lt;BODY.*?&gt;'  '&lt;BODY bgcolor="yellow"&gt;'
1806</PRE>
1807
1808<P>
1809Note that the spacing and capitalization of the keyword are ignored. So you can also do <CODE>%!Target:htm…
Large files files are truncated, but you can click here to view the full file