"Hi! I'm the txt2tags manual document.

Here you'll find all available information about the txt2tags text conversion tool.

This chapter is a txt2tags overview, that will introduce the program purpose and features.

Txt2tags is a text formatting and conversion tool.

Txt2tags converts a plain text file with little marks, to any of the supported targets:

• HTML document
• SGML document
• LaTeX document
• UNIX man page
• MoinMoin page
• Magic Point presentation
• PageMaker 6.0 document

You'll find txt2tags really useful if you:

• need to publish documents on different formats
• need to maintain updated documents on different formats
• write technical or manual documents
• don't know how to write a document on a certain format
• don't have a specific editor for a certain format
• want to use a simple text editor to update your documents

• save time, writing contents and forgetting about formatting

Txt2tags has a very straight way of growing, following basic concepts. These are the highlights:

Source file readable	Txt2tags marks are very simplistic, almost natural.
Target document readable	As the source file, the target document is readable also, with indentation and short lines.
Marks consistent	Txt2tags marks are unique enough to fit at all kind of documents and don't be confused with the document contents.
Rules consistent	As the marks, the rules that applies to them are tied to each other, there are no "exceptions" or "special cases".
Simple structures	All the supported formatting is simple, with no extra-options or complicated behaviour modifiers. A mark is just a mark, with no options at all.
Easy to learn	With simple marks and source readable, the txt2tags learning curve is user friendly.
Nice examples	The sample files included on the package gives real life examples of simple and over-complicated documents written on the txt2tags format.
Valuable Tools	The syntax files included on the package (for vim and emacs editors) help you to write documents with no syntax errors.
Three user interfaces	There is a Graphical Tk interface that is very user friendly, a Web interface to use it remotely or on the intranet, and a Command Line interface for powerusers and scripting.
Scripting	With the full featured comand line mode, an experienced user can automatize tasks and do post-editting on the converted files.
Download and run / Multi-platform	Txt2tags is a single Python script. There is no need to compile it or download extra modules. So it runs nicely on *NIX, Linux, Windows and Macintosh machines.
Frequent Updates	The program has a mailing list with active users who suggest corrections and improvements. The author himself is an extensive user at home and at work, so the development won't stop briefly.

Absolutely NO!

It's free, GPL, open source, public domain, <put-your-favorite-buzzword-here>.

You can copy, use, modify, sell, release as yours. Software politics/copyright is not one of the author's major concern.

On this section the program features will be seen in a detailed form, solving the doubts you may have about it.

The following is a list of all the structures supported by txt2tags.

• header (document title, author name, date)
• section title
• paragraphs
• font beautifiers
  • bold
  • italic
  • bold-italic
  • underline
• preformatted font (verbatim)
  • preformatted inside paragraph
  • preformatted line
  • preformatted area (multiline)
• quoted area
• link
  • URL/internet links
  • e-mail links
  • local links
  • named links
• lists
  • bulleted list
  • numbered list
  • definition list
• horizontal separator line
• image (with smart alignment)
• table (with or without border)

• special mark for raw text (no parsing)
• special macro for current date
• comments (for self notes, TODO, FIXME)

structure	txt	html	sgml	tex	mgp	pm6	moin	man
headers	Y	Y	Y	Y	Y	N	N	Y
section title	Y	Y	Y	Y	Y	Y	Y	Y
paragraphs	Y	Y	Y	Y	Y	Y	Y	Y
bold	-	Y	Y	Y	Y	Y	Y	Y
italic	-	Y	Y	Y	Y	Y	Y	Y
bold-italic	-	Y	Y	Y	Y	Y	Y	Y
underline	-	Y	-	Y	Y	Y	?	-
preformatted	-	Y	Y	Y	Y	Y	Y	-
preformatted line	-	Y	Y	Y	Y	Y	Y	Y
preformatted area	-	Y	Y	Y	Y	Y	Y	Y
quoted area	Y	Y	Y	Y	Y	Y	?	N
internet links	-	Y	Y	-	-	-	Y	-
e-mail links	-	Y	Y	-	-	-	Y	-
local links	-	Y	Y	N	-	-	Y	-
named links	-	Y	Y	-	-	-	Y	-
bulleted list	Y	Y	Y	Y	Y	Y	Y	Y
numbered list	Y	Y	Y	Y	Y	Y	Y	N
definition list	Y	Y	?	Y	N	N	N	Y
horizontal line	Y	Y	-	Y	Y	N	Y	-
image	-	Y	Y	N	Y	N	Y	-
table	N	Y	Y	Y	N	N	Y	N

Legend:

  Y   supported
  N   not supported (may be in future releases)
  -   not supported (can't be done on this target)
  ?   not supported (not sure if it can be done or not)

First of all, you must download and install the Python interpreter on your system. If you already have it, just skip this step.

As a single Python script, txt2tags needs no installation at all.

The only needed file to use the program is the txt2tags script. The other files of the tarball are documentation, tools and sample files.

The fail-proof way to run txt2tags, is calling Python with it:

  prompt$ python txt2tags

If you want to "install" txt2tags on the system as a stand alone program, just copy (or link) the txt2tags script to a System PATH directory and make sure the system knows how to run it.

UNIX/Linux

Make the script executable (chmod +x txt2tags) and copy it to a $PATH directory (cp txt2tags /usr/bin)

Windows

Rename the script adding the .py extension (ren txt2tags txt2tags.py) and copy it to a system PATH directory (copy txt2tags.py C:\WINNT)

Txt2tags has three user interfaces. Now we will take a look at them.

Since version 1.0, there is a nice Graphical Interface, that works on Linux, Windows and Mac (and others).

It's pretty simple and easy to use:

And it also has the ability to dump the result file to a window, instead of writing to the disc, so you can do quick testings before save the target file:

For command line powerusers, the --help should be enough:

  usage: txt2tags -t <type> [OPTIONS] file.t2t
         txt2tags -t html -s <split level> -l <lang> file.t2t
  
    -t, --type       target document type. actually supported:
                     txt, sgml, html, pm6, mgp, moin, man, tex
  
        --stdout     by default, the output is written to file.<type>
                     with this option, STDOUT is used (no files written)
        --noheaders  suppress header, title and footer information
        --enumtitle  enumerate all title lines as 1, 1.1, 1.1.1, etc
        --maskemail  hide email from spam robots. x@y.z turns to <x (a) y z>
  
        --toc        add TOC (Table of Contents) to target document
        --toconly    print document TOC and exit
        --gui        invoke Graphical Tk Interface
  
    -h, --help       print this help information and exit
    -V, --version    print program version and exit
  
  extra options for HTML target (needs sgml-tools):
        --split      split documents. values: 0, 1, 2 (default 0)
        --lang       document language (default english)

Examples

Assuming you have written a file.t2t marked file, let's have some converting fun.

Convert to HTML	$ txt2tags -t html file.t2t
The same, using redirection	$ txt2tags -t html --stdout file.t2t > file.html
	.
Including Table Of Contents	$ txt2tags -t html --toc file.t2t
And also, numbering titles	$ txt2tags -t html --toc --enumtitle file.t2t
	.
Contents quick view	$ txt2tags --toconly file.t2t
Maybe enumerate them?	$ txt2tags --toconly --enumtitle file.t2t
	.
Oneliners from STDIN	$ echo -e "\n**bold**" | txt2tags -t html --noheaders -
Testing Mask Email feature	$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --maskemail --noheaders -
Post-convert editting	$ txt2tags -t html --stdout file.t2t | sed "s/^<BODY .*/<BODY BGCOLOR=green>/" > file.html

Txt2tags marked files are divided in 3 areas. Each area have its own rules and purpose. They are:

Headers Area

Place for Document Title, Author, Version and Date information. (optional)

Settings Area

Place for general Document Settings and Parser behaviour modifiers. (optional)

Body Area

Place for the Document Content. (required)

The areas are delimited by special rules, which will be seen ahead. For now, this is a graphical representation of the areas on a document:

               ____________
              |            |
              |   HEADERS  |       1. First, the Headers
              |            |
              |  SETTINGS  |       2. Then the Settings
              |            |
              |    BODY    |       3. And finally the Document Body,
              |            |
              |    ...     |          which goes until the end
              |    ...     |
              |____________|
  

In short, this is how the areas are defined:

Headers	First 3 lines of the file, or the first line blank for No Headers.
Settings	Begins right after the Header (4th or 2nd line) and ends when the Body Area starts.
Body	The first valid text line (not comment or setting) after the Headers Area.

Location:

• Fixed position: First 3 lines of the file. Dot.
• Fixed position: First line of the file if it is blank. This means Empty Headers.

These lines are content-free, with no static information type needed. But the following is recomended for the most documents:

• line 1: document title
• line 2: author name and/or email
• line 3: document date and/or version (nice place for %%date)

Less (or None) Header lines

Sometimes user wants to specify less then tree lines for headers, giving just document title and/or date information.

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 after the 3rd line anyway.

The title is the only required header (the first line), but if you leave it blank, you are saying that your document has no headers. So the Body Area will begin right after, on the 2nd line.

This is useful to use together with the command line --noheaders option.

Straight to the point

In short: "Headers are just positions, not contents".

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.

Location:

• Begins right after the Headers Area
  • Begins on the 4th line of the file if Headers were specified
  • Begins on the 2nd line of the file if No Headers were specified
• Ends when the Body Area starts
  • Ends by a non Setting, Blank or Comment line

So, how to set something? What's the syntax?

Setting lines are special comment lines, marked by a leading identifier ("!") that makes them different from plain comments. The syntax is just as simple as variable setting, composed by a keyword and a value, separated from each other by the canonical separator colon (":"). Example:

     %! keyword : value

The exclamation mark should be placed together with the comment char ("%!"), no spaces between them. The spaces around keyword and the separator are optional, and both keyword and value are case insensitive (case doesn't matter).

What can i set? Which are the valid keywords?

For now, the only setting that could be done is Encoding. It's needed by non-english writters, who uses accented letters and other locale specific details, so the target document Character Set must be customized (if allowed).

A real life example is:

    %! Encoding: iso-8859-1

To specify the latin charset.

Location:

• Begins on the first valid text line of the file
  • Headers, Settings and Comments are not valid text lines
• Ends at the end of the file (EOF)

The body holds the document contents and all formatting and structures txt2tags can recognize. Inside the body you can also put comments for TODOs and self notes.

You can use the --noheaders command line option to convert only the document body, supressing the headers. This is useful to set your own headers on a separate file, then join the converted body.

  My nice doc Title
  Mr. John Doe
  Last Updated: %%date(%c)
  
  %! Encoding: iso8859-1
  
  Hi! This is my test document.
  Its content will end here.

The %%date macro called alone, returns the current date on the ISO yyyymmdd format. Optional formatting can be specified using the %%date(format-string) format.

This format-string is made of plain text plus the formatting directives, which are a percent sign % followed by an identification character.

On July 2001, was launched the first public release of txt2tags (v0.1). But its origins date more than an year before that...

This chapter illustrates in a few words the tool development since its very first draw until the current series.

From the author:

"My really first attempts of a text conversion tool began back in 1999, as a very simple and limited Bourne Shell script that convert marked text to an HTML page. Yes, Yet-Another txt2html tool. Everyone Everywhere already must have done one of this... In short, it just recognized simple marks as *bold*, /italic/, _under_, and escape the classic < & > HTML special characters. Not impressive, but hey! I was young ;)"

The author wants to speak some more:

"Some months passed, and a big Sgml hype arrived at the company I was working (Conectiva). So the txt2html turned into a txt2sgml script. I was really trying to learn about SED* at that moment so txt2sgml was a 110 lines Bourne Shell script with lots of SED code."

* SED: UNIX Stream EDitor - an automatic text editing tool

This improved Sgml version had more supported structures as lists and preformatted text. On the following sample file, you can see the txt2tags marks origins:

  		 * This was a bold line (BOLD line oriented? well...)
  
  		   --
  		 - bullet list was very similar to txt2tags list
  		 - but with these -- to begin and close a list
  		   --
  
  		 =----------------------
  		 Preformatted text was delimited by the =-- pattern.
  		 The other ------- was just cosmetic.
  		 =----------------------

Still not impressive, but the big step is comming...

TODO (txt2sgml.sed)

TODO

Announce

This release starts my 1.x series.

More than a year of almost-monthly updates, and the 0.x series provided me a nice set of features, as Command Line and Web interface, TOC handling, numbering titles and lists, STDIN/STDOUT facilities, vim/emacs syntax files and seven supported target formats.

For the incoming 1.x series, I'll try to spread myself out, providing a nice GUI, extensive documentation, mailing list, user base, Unix/Windows/Mac full compatibility and including more targets (as tex, rtf and xhtml).

On this 1.0 release I'm already at full speed ahead, with a new suit (Graphical Tk Interface) and compatibility with Unix/Windows/Mac, handling line breaks and other platform specific issues. Fortunely, now my master can reach Linux, Windows 2000, Cygwin and MacOS 8.6 systems for testing me.