/doc/English/userguide/userguide.html
http://txt2tags.googlecode.com/ · HTML · 3589 lines · 3457 code · 131 blank · 1 comment · 0 complexity · c0fe9b895ad72f0cb4c9dc464dd836c9 MD5 · raw file
Large files are truncated click here to view the full file
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
- <!-- This document was generated from userguide.t2t -->
- <HTML>
- <HEAD>
- <META NAME="generator" CONTENT="http://txt2tags.org">
- <LINK REL="stylesheet" TYPE="text/css" HREF="userguide.css">
- <TITLE>Txt2tags User Guide</TITLE>
- </HEAD>
- <BODY>
- <DIV CLASS="header" ID="header">
- </DIV>
- <DIV CLASS="body" ID="body">
- <H1>About</H1>
- <P>
- This is the <A HREF="http://txt2tags.org">txt2tags</A> User Guide, the
- complete manual about the program.
- </P>
- <UL>
- <LI>User Guide official address:
- <A HREF="http://txt2tags.org/userguide">http://txt2tags.org/userguide</A>
- <P></P>
- <LI>User Guide PDF download:
- <A HREF="http://txt2tags.org/userguide/userguide.pdf">http://txt2tags.org/userguide/userguide.pdf</A>
- </UL>
- <A NAME="intro"></A>
- <H1>Part I - Introducing Txt2tags</H1>
- <A NAME="1st-questions"></A>
- <H2>The First Questions You May Have</H2>
- <P>
- This chapter is a txt2tags overview, that will introduce the program
- purpose and features.
- </P>
- <H3>What is it?</H3>
- <P>
- Txt2tags is a text formatting and conversion tool.
- </P>
- <DL>
- <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>
- <P></P>
- <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>
- <P></P>
- Amongs others, there are:
- <P></P>
- </DL>
- <UL>
- <LI>popular Wiki markups, such as bbcode, wikipedia pages, markdown, restructuredtext and spip.
- <P></P>
- <LI>html variations: html transitional, xhtml, html5...
- <P></P>
- <LI>office documents: RTF, LaTeX documents, Open Document Spreadsheet, SQLite database (imported from tables)
- <P></P>
- <LI>plain text, including ASCII art variations.
- </UL>
- <P>
- <I>See the <A HREF="#targets">targets chapter</A> to discover the full list.</I>
- </P>
- <DL>
- <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>
- </DL>
- <H3>Why should I use it?</H3>
- <P>
- You'll find txt2tags really useful if you:
- </P>
- <UL>
- <LI>Need to publish documents in different formats
- <LI>Need to maintain updated documents in different formats
- <LI>Write technical documents or guides
- <LI>Don't know how to write a document in a specific format
- <LI>Don't have an editor for a specific format
- <LI>Want to use a simple text editor to update your documents
- </UL>
- <P>
- And the main motivation is:
- </P>
- <UL>
- <LI>Save time, writing <B>contents</B> and forgetting about <B>formatting</B>
- </UL>
- <H3>Why is it a good choice among other tools?</H3>
- <P>
- Txt2tags has a very straight way of growing, following basic concepts.
- These are the highlights:
- </P>
- <TABLE>
- <TR>
- <TD><I>Source File Readable</I></TD>
- <TD>Txt2tags marks are very simple, almost natural.</TD>
- </TR>
- <TR>
- <TD><I>Target Document Readable</I></TD>
- <TD>The target document is also readable, with indentation and spacing.</TD>
- </TR>
- <TR>
- <TD><I>Consistent Marks</I></TD>
- <TD>Txt2tags marks are simple symbols, designed to be unique enough to don't mix up with the document contents.</TD>
- </TR>
- <TR>
- <TD><I>Consistent Rules</I></TD>
- <TD>As the marks, the rules that applies to them are tied to each other, there are no "exceptions" or "special cases".</TD>
- </TR>
- <TR>
- <TD><I>Simple Structures</I></TD>
- <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>
- </TR>
- <TR>
- <TD><I>Easy to Learn</I></TD>
- <TD>With simple marks and readable source, the txt2tags learning curve is user friendly.</TD>
- </TR>
- <TR>
- <TD><I>Nice Examples</I></TD>
- <TD>The <B>sample files</B> included on the package gives real life examples of documents written for txt2tags.</TD>
- </TR>
- <TR>
- <TD><I>Valuable Tools</I></TD>
- <TD>The <B>syntax files</B> included on the package help you to write documents with no syntax errors.</TD>
- </TR>
- <TR>
- <TD><I>Three User Interfaces</I></TD>
- <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>
- </TR>
- <TR>
- <TD><I>Scripting</I></TD>
- <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>
- </TR>
- <TR>
- <TD><I>Download and Run / Multi-platform</I></TD>
- <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>
- </TR>
- <TR>
- <TD><I>Mature</I></TD>
- <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>
- </TR>
- </TABLE>
- <H3>Do I have to pay for it?</H3>
- <P>
- Absolutely NO!
- </P>
- <P>
- It's free, GPL licensed.
- </P>
- <A NAME="structures"></A>
- <H2>Supported Formatting Structures</H2>
- <P>
- The following is a list of all the structures supported by txt2tags.
- </P>
- <UL>
- <LI>header (document title, author name, date)
- <LI>section title (numbered or not)
- <LI>paragraphs
- <LI>font beautifiers
- <UL>
- <LI>bold
- <LI>italic
- <LI>underline
- <LI>strike
- </UL>
- <LI>monospaced font (verbatim)
- <UL>
- <LI>monospaced inside paragraph
- <LI>monospaced line
- <LI>monospaced area (multiline)
- </UL>
- <LI>quoted area
- <LI>link
- <UL>
- <LI>URL/Internet links
- <LI>e-mail links
- <LI>local links
- <LI>named links
- </UL>
- <LI>lists
- <UL>
- <LI>bulleted list
- <LI>numbered list
- <LI>definition list
- </UL>
- <LI>horizontal separator line
- <LI>image (with smart alignment)
- <LI>table (with or without border, smart alignment, column span)
- <LI>macros (with flexible formatting):
- <UL>
- <LI>current date
- <LI>file modification time
- <LI>input and output file name and path
- <LI>automatic table of contents
- </UL>
- <LI>special mark for raw text (no marks parsed inside)
- <LI>special mark for tagged text (no parsing, sent directly to output)
- <LI>comments (for self notes, TODO, FIXME)
- </UL>
- <A NAME="targets"></A>
- <H2>Supported Targets</H2>
- <H3>Wiki</H3>
- <DL>
- <DT><B>adoc</B></DT><DD>
- AsciiDoc document
- <P></P>
- <DT><B>bbcode</B></DT><DD>
- BBCode document
- <P></P>
- <DT><B>creole</B></DT><DD>
- Creole 1.0 document
- <P></P>
- <DT><B>DOKU</B></DT><DD>
- <A HREF="http://www.dokuwiki.org/dokuwiki">DokuWiki</A> is a standards
- compliant, simple to use Wiki, mainly aimed at creating documentation
- of any kind. It is targeted at developer teams, workgroups and small
- companies. It has a simple but powerful syntax which makes sure the
- data files remain readable outside the Wiki and eases the creation of
- structured texts. All data is stored in plain text files - no
- database is required.
- </DL>
- <DL>
- <DT><B>Foswiki / TWiki</B></DT><DD>
- <A HREF="http://foswiki.org/">Foswiki</A> or <A HREF="http://twiki.org">TWiki</A>, is a flexible, powerful,
- and easy to use enterprise wiki and collaboration platform.
- The structured wiki is typically used to run a project development
- space, a document management system, a knowledge base, or any other
- groupware tool, on an intranet or on the internet.
- <P></P>
- <DT><B>GWIKI</B></DT><DD>
- Now you can easily paste your project's current documentation into the
- <A HREF="http://code.google.com/">Google Code</A> Wiki.
- <P></P>
- <DT><B>md</B></DT><DD>
- Markdown document
- <P></P>
- <DT><B>MOIN</B></DT><DD>
- You don't know what <A HREF="http://moinmo.in/">MoinMoin</A> is?
- It is a <A HREF="http://www.c2.com/cgi/wiki">WikiWiki</A>!
- <P></P>
- Moin syntax is kinda boring when you need to keep
- <CODE>{{{'''''adding braces and quotes'''''}}}</CODE>, so txt2tags comes with the
- simplified marks and unified solution: one source, multi targets.
- <P></P>
- <DT><B><A HREF="http://en.wikipedia.org/wiki/PmWiki">PMWIKI</A></B></DT><DD>
- <A HREF="http://www.pmwiki.org/">PmWiki</A> is a light and free wiki software written in PHP, and using no SQL database.
- <P></P>
- <DT><B>red</B> </DT><DD>
- Redmine Wiki page
- <P></P>
- <DT><B>rst</B></DT><DD>
- ReStructuredText document
- <P></P>
- <DT><B>spip</B></DT><DD>
- SPIP article
- <P></P>
- <DT><B>txt2t</B></DT><DD>
- Txt2tags document
- <P></P>
- <DT><B>WIKI</B></DT><DD>
- You've heard about the <A HREF="http://wikipedia.org">Wikipedia</A>, right? So you
- don't need to learn yet-another markup syntax. Just stick with txt2tags
- and let it convert your text to the Wikipedia format, called
- <A HREF="http://en.wikipedia.org/wiki/MediaWiki">MediaWiki</A>.
- </DL>
- <H3>HTML</H3>
- <DL>
- <DT><B>aapw</B></DT><DD>
- ASCII Art Presentation Web
- <P></P>
- <DT><B>aasw</B></DT><DD>
- ASCII Art Spreadsheet Web
- <P></P>
- <DT><B>aatw</B></DT><DD>
- ASCII Art Text Web
- <P></P>
- <DT><B><A HREF="http://en.wikipedia.org/wiki/HTML">HTML</A></B></DT><DD>
- You maybe know what HTML is. (hint: Internet)
- <P></P>
- Txt2tags generates clean HTML documents, that look pretty and have
- its source readable. It DOES NOT use javascript, frames or other
- futile formatting techniques, that aren't required for simple, techie
- documents. But a separate CSS file can be used if wanted. Txt2tags
- generates "<I>HTML 4.0 Transitional</I>" code.
- <P></P>
- Txt2tags HTML generated code is 100% approved by the <A HREF="http://validator.w3.org/">w3c validator</A>.
- <P></P>
- <DT><B>html5</B></DT><DD>
- HTML5 page
- <P></P>
- <DT><B>htmls</B></DT><DD>
- HTML Spreadsheet
- <P></P>
- <DT><B>wp</B></DT><DD>
- WordPress post
- <P></P>
- <DT><B><A HREF="http://en.wikipedia.org/wiki/XHTML">XHTML</A></B></DT><DD>
- It is the new generation of HTML, with more strict rules.
- This makes the code easier to parse and
- understand. For the general purpose, consider it HTML. Txt2tags
- generates "<I>XHTML 1.0 Transitional</I>" code.
- <P></P>
- Txt2tags XHTML generated code is 100% approved by the <A HREF="http://validator.w3.org/">w3c validator</A>.
- <P></P>
- <DT><B>xhtmls</B></DT><DD>
- XHTML Strict page
- </DL>
- <H3>Office</H3>
- <DL>
- <DT><B>csv</B></DT><DD>
- CSV spreadsheet
- <P></P>
- <DT><B>db</B></DT><DD>
- SQLite database
- <P></P>
- <DT><B>dbk</B></DT><DD>
- DocBook document
- <P></P>
- <DT><B>LOUT</B></DT><DD>
- Very similar to LaTeX in power, but with an easier syntax using "@"
- instead "\" and avoiding the need of braces in common situations. Its
- approach of everything-is-an-object makes the tagging much saner.
- <P></P>
- Txt2tags generates ready-to-use Lout files, which can be converted do
- PS or PDF files using the "lout" command.
- <P></P>
- <DT><B>MGP</B></DT><DD>
- <A HREF="http://en.wikipedia.org/wiki/MagicPoint">MagicPoint</A> is a very handy presentation tool
- (hint: Microsoft PowerPoint), that uses a tagged language to define all
- the screens. So you can do complex presentations in vi/emacs/notepad.
- <P></P>
- Txt2tags generates a ready-to-use .mgp file, defining all the
- necessary headers for fonts and appearance definitions, as long as
- international characters support.
- <P></P>
- Txt2tags creates "diet" .mgp files: they use the Type1 fonts, so you do not
- need to carry TrueType fonts files with your presentation. Also, the color
- definitions are simple, so even on a poor color palette system (such as
- <CODE>startx -- -bpp 8</CODE>), the presentation will look pretty!
- <P></P>
- The key is: convert and use. No quick fixes or requirements needed.
- <P></P>
- <DT><B>ods</B></DT><DD>
- Open Document Spreadsheet
- <P></P>
- <DT><B>PM6</B></DT><DD>
- Adobe PageMaker 6.0 has its own tagged
- language. Styles, color table, beautifiers, and most of all the
- PageMaker mouse-clicking features are also available on its tagged language.
- You just need to access the "Import tagged text" menu item. Just for
- the records, it's an <HTML "like"> tag format.
- <P></P>
- Txt2tags generates all the tags and already defines a extensive and
- working header, setting paragraph styles and formatting. This is the
- hard part.
- <P></P>
- <B>Author's note:</B>
- My entire portuguese <A HREF="http://guia-er.sf.net">regular expression's book</A>
- was written in VI, then converted to PageMaker with txt2tags and went to
- the publisher. It works :)
- <P></P>
- <DT><B>rtf</B></DT><DD>
- RTF document
- <P></P>
- <DT><B><A HREF="http://en.wikipedia.org/wiki/SGML">SGML</A></B></DT><DD>
- It is a common document format which has powerful conversion applications
- (<A HREF="http://packages.debian.org/linuxdoc-tools">linuxdoc-tools</A>). From a
- single SGML file you can generate HTML, PDF, PostScript, Info, LaTeX, LyX, RTF
- and XML documents. The tools also does automatic TOC and break
- sections into subpages.
- <P></P>
- Txt2tags generates SGML files in the LinuxDoc system type, ready to
- be converted with linuxdoc-tools without any extra catalog files or any
- SGML annoying requirements.
- <P></P>
- <DT><B><A HREF="http://en.wikipedia.org/wiki/LaTeX">LATEX</A></B></DT><DD>
- The preferred academic document format, it is more powerful than you
- ever wondered. Full books, complicated formulas and any complex text
- can be written in LaTeX. But prepare to loose your hair when you try
- to write the tags by hand...
- <P></P>
- Txt2tags generates ready-to-use LaTeX files, doing all the complex
- escaping tricks and exceptions. The writer just need to worry about
- the text.
- <P></P>
- <DT><B>texs</B></DT><DD>
- LaTeX Spreadsheet
- </DL>
- <H3>Text</H3>
- <DL>
- <DT><B>aap</B></DT><DD>
- ASCII Art Presentation
- <P></P>
- <DT><B>aas</B></DT><DD>
- ASCII Art Spreadsheet
- <P></P>
- <DT><B>aat</B></DT><DD>
- ASCII Art Text
- <P></P>
- <DT><B>MAN</B></DT><DD>
- UNIX man pages resist over the years. Document formats come and go,
- and there they are, unbeatable.
- <P></P>
- There are other tools to generate man documents, but txt2tags has
- one advantage: one source, multi targets. So the same man page
- contents can be converted to an HTML page, Wiki document and plain text.
- <P></P>
- <DT><B>TXT</B></DT><DD>
- TXT is text. Simple, pure, beautiful.
- <P></P>
- Although txt2tags marks are very intuitive and discrete, you can remove
- them by converting the file to pure TXT.
- <P></P>
- The titles are underlined, and the text is basically left as is on the
- source.
- </DL>
- <P>
- Tip: Use the <CODE>--targets</CODE> command line option to get a complete list of
- all the available targets.
- </P>
- <A NAME="struct-support"></A>
- <H2>Status of Supported Structures by Target</H2>
- <TABLE ALIGN="center" BORDER="1">
- <TR>
- <TH>Structure</TH>
- <TH>html</TH>
- <TH>xhtml</TH>
- <TH>sgml</TH>
- <TH>dbk</TH>
- <TH>tex</TH>
- <TH>lout</TH>
- <TH>man</TH>
- <TH>mgp</TH>
- <TH>creole</TH>
- <TH>wiki</TH>
- <TH>gwiki</TH>
- <TH>pmw</TH>
- <TH>doku</TH>
- <TH>moin</TH>
- <TH>pm6</TH>
- <TH>adoc</TH>
- <TH>art</TH>
- <TH>txt</TH>
- <TH>tml</TH>
- </TR>
- <TR>
- <TD>headers</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>section title</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>paragraphs</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>bold</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>italic</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>underline</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>strike</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>monospaced font</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>verbatim line</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>verbatim area</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>quoted area</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>internet links</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>e-mail links</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>local links</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>named links</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>bulleted list</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>numbered list</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>definition list</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>horizontal line</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>image</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>table</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TH>Extras</TH>
- <TH>html</TH>
- <TH>xhtml</TH>
- <TH>sgml</TH>
- <TH>dbk</TH>
- <TH>tex</TH>
- <TH>lout</TH>
- <TH>man</TH>
- <TH>mgp</TH>
- <TH>creole</TH>
- <TH>wiki</TH>
- <TH>gwiki</TH>
- <TH>pmw</TH>
- <TH>doku</TH>
- <TH>moin</TH>
- <TH>pm6</TH>
- <TH>adoc</TH>
- <TH>art</TH>
- <TH>txt</TH>
- <TH>Y</TH>
- </TR>
- <TR>
- <TD>image align</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>table cell align</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- <TR>
- <TD>table column span</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">Y</TD>
- </TR>
- </TABLE>
- <TABLE ALIGN="center">
- <TR>
- <TH></TH>
- <TH>Legend</TH>
- </TR>
- <TR>
- <TD><B>Y</B></TD>
- <TD><I>Supported</I></TD>
- </TR>
- <TR>
- <TD><B>N</B></TD>
- <TD><I>Not supported (may be in future releases)</I></TD>
- </TR>
- <TR>
- <TD><B>-</B></TD>
- <TD><I>Not supported (can't be done on this target)</I></TD>
- </TR>
- </TABLE>
- <A NAME="interfaces"></A>
- <H2>The Three User Interfaces: Gui, Web and Command Line</H2>
- <P>
- As different users have different needs and environments, txt2tags is
- very flexible on how it runs.
- </P>
- <P>
- There are three User Interfaces for the program, each one with its own
- purpose and features.
- </P>
- <UL>
- <LI><B>Gui</B>: Written in Tk, brings the windowing and clicking to txt2tags.
- <LI><B>Web</B>: Written in PHP, allows users to run txt2tags on the browser,
- requiring no installation on the client side.
- <LI><B>Command Line</B>: Written in Python, it's the program core. All
- features are available as command line options.
- </UL>
- <A NAME="gui"></A>
- <H3>Graphical Interface</H3>
- <P>
- Since version 1.0, there is a nice Graphical Interface, that works on
- Linux, Windows, Mac and others. Just call txt2tags with the <CODE>--gui</CODE>
- option to open it.
- </P>
- <P>
- The interface is pretty simple and intuitive:
- </P>
- <center><IMG ALIGN="middle" SRC="./gui.png" BORDER="0" ALT=""></center>
- <OL>
- <LI>You locate the source .t2t file on the disk and its options are
- loaded.
- <P></P>
- <LI>If the target is still empty, you must choose one.
- <P></P>
- <LI>Then there are some options you may choose, but none of them are
- required.
- <P></P>
- <LI>Finally, press the "Convert!" button.
- </OL>
- <P>
- A nice option is the "<I>Dump to screen</I>", so you can check
- the resulting code on a separate window, no file is saved at all. When
- the code is OK, you uncheck it and the file will be saved.
- </P>
- <P>
- The default interface colors can be changed on the <A HREF="#rc">configuration file</A>,
- using the <CODE>%!guicolors</CODE> settings. For example:
- </P>
- <PRE>
- % set my own colors for the graphical interface (bg1, fg1, bg2, fg2)
- %!guicolors: blue white brown yellow
- </PRE>
- <H3>Web Interface</H3>
- <P>
- The Web Interface is up and running on the Internet at
- <A HREF="http://txt2tags.org/online.php">http://txt2tags.org/online.php</A>, so you can use and test the program
- instantly, before download.
- </P>
- <center><IMG ALIGN="middle" SRC="./web.png" BORDER="0" ALT=""></center>
- <P>
- One can also put this interface on the local intranet avoiding to
- install txt2tags in all machines.
- </P>
- <A NAME="cmdline"></A>
- <H3>Command Line Interface</H3>
- <P>
- For command line power users, the --help should be enough:
- </P>
- <PRE>
- Usage: txt2tags [OPTIONS] [infile.t2t ...]
- --targets print a list of all the available targets and exit
- -t, --target=TYPE set target document type. currently supported:
- adoc, art, creole, dbk, doku, gwiki, html, lout, man,
- mgp, moin, pm6, pmw, sgml, tex, txt, wiki, xhtml
- -i, --infile=FILE set FILE as the input file name ('-' for STDIN)
- -o, --outfile=FILE set FILE as the output file name ('-' for STDOUT)
- --encoding=ENC set target file encoding (utf-8, iso-8859-1, etc)
- --toc add an automatic Table of Contents to the output
- --toc-level=N set maximum TOC level (depth) to N
- --toc-only print the Table of Contents and exit
- -n, --enum-title enumerate all titles as 1, 1.1, 1.1.1, etc
- --style=FILE use FILE as the document style (like HTML CSS)
- --css-sugar insert CSS-friendly tags for HTML/XHTML
- --css-inside insert CSS file contents inside HTML/XHTML headers
- -H, --no-headers suppress header and footer from the output
- --mask-email hide email from spam robots. x@y.z turns <x (a) y z>
- --slides format output as presentation slides (used by -t art)
- --width=N set the output's width to N columns (used by -t art)
- --height=N set the output's height to N rows (used by -t art)
- -C, --config-file=F read configuration from file F
- --gui invoke Graphical Tk Interface
- -q, --quiet quiet mode, suppress all output (except errors)
- -v, --verbose print informative messages during conversion
- -h, --help print this help information and exit
- -V, --version print program version and exit
- --dump-config print all the configuration found and exit
- --dump-source print the document source, with includes expanded
- Turn OFF options:
- --no-css-inside, --no-css-sugar, --no-dump-config, --no-dump-source,
- --no-encoding, --no-enum-title, --no-headers, --no-infile,
- --no-mask-email, --no-outfile, --no-quiet, --no-rc, --no-slides,
- --no-style, --no-targets, --no-toc, --no-toc-only
- Example:
- txt2tags -t html --toc file.t2t
- By default, converted output is saved to 'infile.<target>'.
- Use --outfile to force an output file name.
- If input file is '-', reads from STDIN.
- If output file is '-', dumps output to STDOUT.
- </PRE>
- <P>
- Please read the txt2tags man page for detailed information about options and command line use.
- </P>
- <P>
- Examples:
- </P>
- <TABLE>
- <TR>
- <TD><B>Convert to HTML</B></TD>
- <TD><CODE>$ txt2tags -t html file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD><B>The same, using redirection</B></TD>
- <TD><CODE>$ txt2tags -t html -o - file.t2t > file.html</CODE></TD>
- </TR>
- <TR>
- <TD></TD>
- <TD>.</TD>
- </TR>
- <TR>
- <TD><B>Including Table Of Contents</B></TD>
- <TD><CODE>$ txt2tags -t html --toc file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD><B>And also, numbering titles</B></TD>
- <TD><CODE>$ txt2tags -t html --toc --enum-title file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD></TD>
- <TD>.</TD>
- </TR>
- <TR>
- <TD><B>Contents quick view</B></TD>
- <TD><CODE>$ txt2tags --toc-only file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD><B>Maybe enumerate them?</B></TD>
- <TD><CODE>$ txt2tags --toc-only --enum-title file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD></TD>
- <TD>.</TD>
- </TR>
- <TR>
- <TD><B>One liners from STDIN</B></TD>
- <TD><CODE>$ echo -e "\n**bold**" | txt2tags -t html --no-headers -</CODE></TD>
- </TR>
- <TR>
- <TD><B>Testing Mask Email feature</B></TD>
- <TD><CODE>$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -</CODE></TD>
- </TR>
- </TABLE>
- <A NAME="install"></A>
- <H1>Part II - Install</H1>
- <P>
- Just download the program and run it on your machine.
- </P>
- <A NAME="download-python"></A>
- <H2>Download & Install Python</H2>
- <P>
- First of all, you must download and install <A HREF="http://www.python.org">Python</A> on
- your system. Txt2tags requires Python version 2.2 or newer.
- </P>
- <P>
- Note that Python is already installed by default in Linux and Mac systems. If you're using those, you're done, just skip this step.
- </P>
- <P>
- If you are not sure if you have Python or not, open a console (tty,
- xterm, MSDOS, Terminal.app) and type <CODE>python</CODE>. If it is not installed, the system
- will tell you.
- </P>
- <A NAME="download-txt2tags"></A>
- <H2>Download txt2tags</H2>
- <P>
- The official location for txt2tags distribution is on the program
- site, at <A HREF="http://txt2tags.org">http://txt2tags.org</A>. Just download and uncompress the package (.tgz file).
- </P>
- <P>
- If you're in Linux, you can also use the automatic installer of your system. Some examples:
- </P>
- <UL>
- <LI>yum install txt2tags
- <LI>sudo apt-get install txt2tags
- </UL>
- <A NAME="install-txt2tags"></A>
- <H2>Install txt2tags</H2>
- <P>
- As a single Python script, txt2tags needs no installation at all.
- </P>
- <P>
- The only file needed to use the program is the txt2tags script. The
- other files of the package are documentation, tools and sample files.
- </P>
- <P>
- The fail-proof way to run txt2tags, is calling Python with it:
- </P>
- <PRE>
- prompt$ python txt2tags
- </PRE>
- <P>
- If you want to install txt2tags on the system as a stand alone
- program, just copy the txt2tags script to a system PATH
- directory and make sure the system knows how to run it.
- </P>
- <DL>
- <DT><B>UNIX/Linux/Mac</B></DT><DD>
- Make the script executable (<CODE>chmod +x txt2tags</CODE>) and copy it to a
- $PATH directory (<CODE>cp txt2tags /usr/local/bin</CODE>)
- <P></P>
- <DT><B>Windows</B></DT><DD>
- Rename the script adding the .py extension
- and copy it to a system PATH directory, such as <CODE>C:\Windows\System32</CODE>.
- </DL>
- <P>
- After that, you can create an icon on your desktop for it, if you want to
- use the program's Graphical Interface.
- </P>
- <A NAME="editor-syntax"></A>
- <H2>Install Text Editor Syntax Highlighting File (optional)</H2>
- <P>
- Txt2tags comes with handy syntax highlighting files to be used by the
- following text editors:
- </P>
- <UL>
- <LI>Vim
- <LI>Emacs
- <LI>Nano
- <LI>Kate
- <LI>Gedit
- <LI>JOE
- <LI>le
- <LI>ne
- <LI>TextMate
- </UL>
- <P>
- This syntax highlighting files have all the txt2tags rules and marks
- registered, helping the user to write error-free documents. Showing the
- marks in colors, you see on-the-fly if you wrote it right.
- </P>
- <TABLE ALIGN="center">
- <TR>
- <TD ALIGN="center"><center><IMG ALIGN="middle" SRC="./vim.png" BORDER="0" ALT=""></center></TD>
- </TR>
- <TR>
- <TD ALIGN="center">Sample file opened in Vim Editor</TD>
- </TR>
- </TABLE>
- <P>
- Each editor has a different install procedure for a syntax highlighting
- file, please read the syntax file headers and the editor documentation.
- </P>
- <A NAME="your-1st-doc"></A>
- <H1>Part III - Writing and Converting Your First Document</H1>
- <H2>Check the Tools</H2>
- <P>
- To make the first conversion you will need three things: txt2tags, a
- text editor and a web browser.
- </P>
- <OL>
- <LI>Make sure txt2tags is installed and running on your system.
- <P></P>
- <UL>
- <LI><B>Command Line Interface:</B> Call "txt2tags" on the command line and
- the program should give you a "Missing input file" message. If it is
- not working, try <CODE>python /path/to/txt2tags</CODE> or even
- <CODE>/path/to/python /path/to/txt2tags</CODE> if Python is not on your PATH.
- <P></P>
- <LI><B>Gui Interface:</B> Click on the program icon to launch the Gui
- Interface or call <CODE>txt2tags --gui</CODE>.
- <P></P>
- </UL>
- <LI>Open the text editor your are comfortable with. It can be <B>any</B> text
- editor, from the good old VI to MS Word or OpenOffice.org. Create a
- brand new empty document to be your first txt2tags one and remember to
- save it as plain text.
- <P></P>
- <LI>Launch your favorite web browser to see the results of the conversion.
- </OL>
- <H2>Write the Document Header</H2>
- <OL>
- <LI>Go to the text editor and on the very first line type the document
- main title: <I>My First Document</I>
- <LI>On the second line make a subtitle, inserting this text:
- <I>A txt2tags test</I>
- <LI>Then, on the third line, put some time information:
- <I>Sunday, 2004</I>
- </OL>
- <P>
- If everything went right, you should be seeing a three line document
- with this contents:
- </P>
- <PRE>
- My First Document
- A txt2tags test
- Sunday, 2004
- </PRE>
- <P>
- This is just a part of the document, but we can already convert it and
- check the results.
- </P>
- <P>
- Now save this document with the name <CODE>test.txt</CODE>. Remember to save it
- as plain text. Pay attention to which folder you are saving the file,
- you will need to remember it soon.
- </P>
- <H2>The First Conversion - Gui Interface</H2>
- <P>
- If you are in the Command Line Interface, please skip this step and read
- the next one.
- </P>
- <P>
- If you are in the Gui Interface, follow this steps:
- </P>
- <center><IMG ALIGN="middle" SRC="./firstdoc.png" BORDER="0" ALT=""></center>
- <OL>
- <LI>Press the "Browse" button and choose the <CODE>test.txt</CODE> you just saved
- (remember the folder!).
- <LI>Back to the first screen, select "HTML page" on the "Target document
- type" combo.
- <LI>Press the "Convert!" button.
- </OL>
- <center><IMG ALIGN="middle" SRC="./firstdoc-done.png" BORDER="0" ALT=""></center>
- <P>
- A dialog box will appear, telling you that the file was converted
- successfully. Note that the generated HTML page was saved on the same
- folder as the text file, with the "html" extension.
- </P>
- <H2>The First Conversion - Command Line Interface</H2>
- <P>
- If you are in the Command Line Interface, move to the folder where the
- file was saved and type this command:
- </P>
- <PRE>
- txt2tags --target html test.txt
- </PRE>
- <P>
- The option <CODE>--target</CODE> is followed
- by the "html" string, which tells the program to what format your text
- file will be converted. The last item is the text filename.
- </P>
- <P>
- The results were saved to the <CODE>test.html</CODE>
- file and then the program will show you the
- "<I>txt2tags wrote test.html</I>" message.
- If some error occurred, read the message carefully.
- </P>
- <P>
- Here is a sample of how it will be shown on your screen:
- </P>
- <PRE>
- prompt$ txt2tags --target html test.txt
- txt2tags wrote test.html
- prompt$
- </PRE>
- <H2>Check the Results</H2>
- <P>
- Open the <CODE>test.html</CODE> file on the web browser to check if everything
- is ok.
- </P>
- <center><IMG ALIGN="middle" SRC="./firstdoc-html.png" BORDER="0" ALT=""></center>
- <P>
- Here it is! You just typed three simple lines of text and txt2tags made
- all the work to set the HTML page heading information, text alignment,
- sizes, spacing and appearance. See that the main title is also placed at the
- browser title bar.
- </P>
- <BLOCKQUOTE>
- You write text, txt2tags does the rest ;)
- </BLOCKQUOTE>
- <P>
- Tip: You can also use CSS files on HTML pages generated by txt2tags, so the
- page appearance is 100% configurable.
- </P>
- <H2>Writing the Document Body</H2>
- <P>
- Now back to the text editor, the next step is to type the document
- contents. You can write plain text as you normally do on email messages.
- You will see that txt2tags recognizes paragraphs and list of items
- automatically, you don't have to "mark" them.
- </P>
- <P>
- Then again: save it, convert and check the results. This is the
- development cycle of a document in txt2tags. You just focus on the
- document contents, finishing documents faster than other editors. No
- mouse clicking, no menus, no windows, no distraction.
- </P>
- <P>
- Considering the following contents for the <CODE>test.txt</CODE> file, which is
- only plain text, compare the generated HTML page:
- </P>
- <PRE>
- My First Document
- A txt2tags test
- Sunday, 2004
- Well, let's try this txt2tags thing.
- I don't know what to write.
- Mmmmmm, I know what I need to do now:
- - Take a shower
- - Eat a pizza
- - Sleep
- </PRE>
- <center><IMG ALIGN="middle" SRC="./firstdoc-fullhtml.png" BORDER="0" ALT=""></center>
- <P>
- You can write a full homepage with 0% of HTML knowledge. You don't need
- to insert any tags. And more, the same text file can be converted to any
- of the other txt2tags supported formats.
- </P>
- <P>
- Besides plain text, txt2tags has some very simple marks, that you'll
- use when you need some other formatting or structures like bold, italic,
- title, images, table and other. As a quick sample,
- <CODE>**stars for bold**</CODE> and <CODE>== equals for title ==</CODE>. You can learn the
- marks on the <A HREF="http://txt2tags.org/markup.html">Txt2tags Markup Demo</A>.
- </P>
- <A NAME="concepts"></A>
- <H1>Part IV - Mastering Txt2tags Concepts</H1>
- <A NAME="areas"></A>
- <H2>The .t2t document Areas</H2>
- <P>
- Txt2tags marked files are divided in 3 areas. Each area has its own
- rules and purpose. They are:
- </P>
- <DL>
- <DT><I>Header Area</I></DT><DD>
- Place for Document Title, Author, Version and Date information.
- <DT><I>Config Area</I></DT><DD>
- Place for general Document Settings and Parser behavior modifiers.
- <DT><I>Body Area</I></DT><DD>
- Place for the Document Content.
- </DL>
- <P>
- All areas are optional. You can write a txt2tags document with just
- headers (such as our first example), or a document with no headers or settings.
- </P>
- <P>
- The areas are delimited by special rules, which will be seen in detail
- on the next chapter. For now, this is a representation of the
- areas on a document:
- </P>
- <PRE>
- ____________
- | |
- | HEADERS | 1. First, the Headers
- | |
- | CONFIG | 2. Then the Settings
- | |
- | BODY | 3. And finally the Document Body,
- | |
- | ... | which goes until the end
- | ... |
- |____________|
- </PRE>
- <P>
- In short, this is how the areas are defined:
- </P>
- <TABLE ALIGN="center">
- <TR>
- <TD ALIGN="center"><B>Headers</B></TD>
- <TD>First 3 lines of the file, or the first line blank for No Headers.</TD>
- </TR>
- <TR>
- <TD ALIGN="center"><B>Config</B></TD>
- <TD>Begins right after the Header (4th or 2nd line) and ends when the <I>Body Area</I> starts.</TD>
- </TR>
- <TR>
- <TD ALIGN="center"><B>Body</B></TD>
- <TD>The first valid text line (not comment or setting) after the <I>Header Area</I>.</TD>
- </TR>
- </TABLE>
- <H3>Full Example</H3>
- <PRE>
- My nice doc Title
- Mr. John Doe
- Last Updated: %%mtime(%c)
- %!target : html
- %!style : fancy.css
- %!encoding: UTF-8
- %!options : --toc --enum-title
- Hi! This is my test document.
- Its content will end here.
- </PRE>
- <A NAME="headers-area"></A>
- <H2>Header Area</H2>
- <P>
- Location:
- </P>
- <UL>
- <LI>Fixed position: <B>First 3 lines</B> of the file. Period.
- <LI>Fixed position: <B>First line</B> of the file if it is blank. This
- means Empty Headers.
- </UL>
- <P>
- The Header Area is the only one that has a fixed position, line
- oriented. They are located at the first three lines of the source file.
- </P>
- <P>
- These lines are content-free, with no static information type needed.
- But the following is recommended:
- </P>
- <UL>
- <LI><I>line 1</I>: document title
- <LI><I>line 2</I>: author name and/or email
- <LI><I>line 3</I>: document date and/or version
- (nice place for <CODE>%%date</CODE>)
- </UL>
- <P>
- Keep in mind that the first 3 lines of the source document will be the
- first 3 lines on the target document, separated and with high contrast
- to the text body (i.e. big letters, bold). If paging is allowed, the
- headers will be alone and centralized on the first page.
- </P>
- <H4>Less (or None) Header lines</H4>
- <P>
- Sometimes the user wants to specify less than three lines for headers,
- giving just the document title and/or date information.
- </P>
- <P>
- Just let the 2nd and/or the 3rd lines empty (blank) and this position
- will not be placed at the target document. But keep in mind that even
- blanks, these lines are still part of the headers, so the document body
- must start <B>after</B> the 3rd line anyway.
- </P>
- <P>
- The title is the only required header (the first line), but if you
- leave it blank, you are saying that your document has <B>no headers</B>.
- So the <I>Body Area</I> will begin right after, on the 2nd line.
- </P>
- <P>
- No headers on the document is often useful if you want to specify your
- own customized headers after converting. The command line option
- <CODE>--no-headers</CODE> is usually required for this kind of operation.
- </P>
- <H4>Straight to the point</H4>
- <P>
- In short: <B>"Headers are just <U>positions</U>, not contents"</B>
- </P>
- <P>
- Place one text on the first line, and it will appear on the target's
- first line. The same for 2nd and 3rd header lines.
- </P>
- <A NAME="config-area"></A>
- <H2>Config Area</H2>
- <P>
- Location:
- </P>
- <UL>
- <LI>Begins right after the Header Area
- <UL>
- <LI>Begins on the <B>4th line</B> of the file if <B>Headers</B> were specified
- <LI>Begins on the <B>2nd line</B> of the file if <B>No Headers</B> were specified
- </UL>
- <LI>Ends when the Body Area starts
- <UL>
- <LI>Ends by a non Setting, Blank or Comment line
- </UL>
- </UL>
- <P>
- The Config Area is optional. An average user can write lots of txt2tags
- files without even know it exists, but the experienced users will
- enjoy the power and control it provides.
- </P>
- <P>
- The Config Area is used to store document-specific settings, so you don't
- have to type them on the command line when converting the document. For
- example, you can set the default document target type and encoding.
- </P>
- <P>
- Please read the <A HREF="#settings-overview">Settings section</A> for more
- information about them.
- </P>
- <A NAME="body-area"></A>
- <H2>Body Area</H2>
- <P>
- Location:
- </P>
- <UL>
- <LI>Begins on the first valid text line of the file
- <UL>
- <LI>Headers, Settings and Comments are <B>not</B> valid text lines
- </UL>
- <LI>Ends at the end of the file (EOF)
- </UL>
- <P>
- The body is anything outside Headers and Config Areas.
- </P>
- <P>
- The body holds the document contents and all formatting and structures
- txt2tags can recognize. Inside the body you can also put comments for
- <I>TODOs</I> and self notes.
- </P>
- <P>
- You can use the <CODE>--no-headers</CODE> command line option to convert only the
- document body, suppressing the headers. This is useful to set your own
- headers on a separate file, then join the converted body.
- </P>
- <A NAME="settings-overview"></A>
- <H2>Settings</H2>
- <P>
- Settings are special configurations placed at the source document's
- Config Area that can affect the conversion process. Their syntax is:
- </P>
- <PRE>
- %! keyword : value
- </PRE>
- <P>
- List of valid keywords:
- </P>
- <TABLE ALIGN="center" BORDER="1">
- <TR>
- <TH>Keyword</TH>
- <TH>Description</TH>
- </TR>
- <TR>
- <TD ALIGN="center">Target</TD>
- <TD>Set the default target to the document be converted to.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">Options</TD>
- <TD>Set the default options to be used on the conversion. The format is the same as the command line options.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">Style</TD>
- <TD>Set the document style. Used to define a CSS file for HTML/XHTML and to load a package in LaTeX.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">Encoding</TD>
- <TD>Set the document Character Set. Used if the document contains accented letters or other not-ASCII characters.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">PreProc</TD>
- <TD>Input filter. Sets "find and replace" rules to be applied on the Body Area of the source document.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">PostProc</TD>
- <TD>Output filter. Sets "find and replace" rules to be applied on the converted document.</TD>
- </TR>
- </TABLE>
- <P>
- Example:
- </P>
- <PRE>
- %!target : html
- %!options : --toc --toc-level 3
- %!style : fancy.css
- %!encoding: UTF-8
- %!preproc : "AMJ" "Aurelio Marinho Jargas"
- %!postproc: '<BODY.*?>' '<BODY bgcolor="yellow">'
- </PRE>
- <P>
- Note that the spacing and capitalization of the keyword are ignored. So you can also do <CODE>%!Target:htm…