txt2tags - text formatting and conversion tool

txt2tags [OPTION]... [FILE]...

txt2tags is a GPL format conversion tool written in Python that generates HTML, XHTML, SGML, LaTeX, Man Page, MoinMoin, Magic Point and PageMaker documents from a single text file with minimal markup.

The user just need to know the very few and simple txt2tags marks, and write plain text files. The program does all the dirty work, adding the complicated tags and dealing with the target document's gotchas.

The same text file can be converted to all target formats, with no further editing. This is the txt2tags purpose: ONE source, MULTI targets.

NOTE: txt2tags Version 2.0 was a complete rewrite for the program core. So, if you are a previous txt2tags user you might need to rewrite some parts of your old source documents.

Please visit the program homepage at http://txt2tags.sourceforge.net.

--css-suggar

insert CSS-friendly tags for HTML and XHTML targets

--dump-config

print all the config found and exit

--encoding

set target file encoding (utf-8, iso-8859-1, etc)

--gui

invoke Graphical Tk Interface

-h, --help

print help information and exit

-H, --no-headers

suppress header, title and footer information

--headers

show header, title and footer information (default ON)

-i, --infile=FILE

set FILE as the input file name ('-' for STDIN)

--mask-email

hide email from spam robots. x@y.z turns <x (a) y z>

-n, --enum-title

enumerate all title lines as 1, 1.1, 1.1.1, etc

--no-encoding

clear the encoding setting

--no-enum-title

turn off the title auto numbering

--no-infile

clear all the previous infile declarations

--no-mask-email

unhide emails, turning off the --mask-email option

--no-outfile

clear the previous outfile declaration

--no-rc

do not read the user config file ~/.txt2tagsrc

--no-style

clear the style setting

--no-toc

do not add TOC (Table of Contents) to target document

--no-toc-only

turn off the --toc-only option

-o, --outfile=FILE

set FILE as the output file name ('-' for STDOUT)

--rc

read user config file ~/.txt2tagsrc (default ON)

--style=FILE

use FILE as the document style (like Html CSS)

-t, --target

set target document type. currently supported: html, xhtml, sgml, tex, man, mgp, moin, pm6, txt

--toc

add TOC (Table of Contents) to target document

--toc-level=N

set maximum TOC level (deepness) to N

--toc-only

print document TOC and exit

-v, --verbose

print informative messages during convertion

-V, --version

print program version and exit

By default, converted output is saved to 'file.<type>'. Use --outfile to force an output file name. If input file is '-', reads from STDIN. If output file is '-', dumps output to STDOUT.

Txt2tags source file can have three areas:

Header

The first three lines. They are used for document identification. If you don't need headers, you must left the first line blank or specify the no-header setting.

Settings

Starts at the fourth line. All settings have the %!keyword: value format. Settings can also be made by a configuration file or command line.

Body

You real document source! Your only request area to have a valid txt2tags file.

Txt2tags can be customized by external and internal methods. The external are a .txt2tagsrc file or imported from another txt2tags file. The internal way is made by special settings commands into the source document. Both use the same syntax:

%!target:

defines the main target

%!options(target):

defines the options to each target

%!include: file.txt

includes a text file in the document

%!include: ''arquivo.html''

includes a literal file in the document, as it is

%!style:

to set a CSS (Cascading Style Sheets) file for XHTML and HTML targets or to load \usepackage modules in TEX target

%!encoding:

to set a character set (like iso-8859-1) for i18n issues

%!includeconf:

used to include configurations from an external file into the current

%!guicolors:

color settings for the gui (tk/tcl) interface

%!preproc:

your customized filter (macro) which will be processed BEFORE the document parsing

%!preproc:

your customized filter (macro) which will be processed AFTER the document parsing

SETTINGS RULES

A very simple markup syntax is used on the document source (the plain text file) to identify structures and formatting. Here's the complete list:

Basic

  Headers           The first 3 lines of the source file
  Title             = words =        
  Numbered title    + words +
  Paragraph         words

Beautifiers

  Bold              **words**
  Italic            //words//
  Underline         __words__
  Verbatim          ``words``

Text Blocks

  Quote             <TAB>words
  List              - words
  Numbered list     + words
  Definition list   : words
  Verbatim line     ``` words
  Verbatim area     ```<LineBreak> lines <LineBreak>```
  Raw line          """ words
  Raw area          """<LineBreak> lines <LineBreak>"""
  Table             | cell1 | cell2 | cell3...

Other

  Separator line    -----------------------...
  Strong line       =======================...
  Links             [label url]
  Image             [filename.XXX]
  Raw Text          ""words""
  Current Date      %%date(format)
  Comment           % comments

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

Convert to HTML, saving to file.html

$ txt2tags -t html file.t2t

The same, using redirection

$ txt2tags -t html -o - file.t2t > file.html

Including Table Of Contents

$ txt2tags -t html --toc file.t2t

Including TOC and numbering titles

$ txt2tags -t html --toc --enum-title file.t2t

Contents quick view

$ txt2tags --toc-only file.t2t

Using Graphical Interface

$ txt2tags --gui file.t2t

Post-convert editing with external filter

$ txt2tags -t html -o- file.t2t | sed -f myfilter.sed > file.html

Quick one-liner test from STDIN

$ echo -e "\n**bold**" | txt2tags -t html -H -

There are a few smart tricks that make txt2tags an excellent documentation tool:

Anchoring

Titles can be linked by anchors, so you can jump into a part of your document directly, if your target allows it

  Title             = words =[anchor]
  Numbered title    + words +[anchor]

Multiple files

Txt2tags can handle more than one file at the same time, like: txt2tags *.t2t

The %%date macro

Allows to include the current date, in the format YYYYMMDD. Optional formatting can be specified using the %%date(format-string) syntax.

Written and maintained by Aurelio Marinho Jargas <verde@aurelio.net>

This Manual Page was written by Jose Inacio Coelho <jic@technologist.com> as a text file, then converted to man format by txt2tags!

Copyright © 2001, 2002, 2003, 2004 Aurelio Marinho Jargas

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.