This is the txt2tags User Guide, the complete manual about the program.
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:
You'll find txt2tags really useful if you:
And the main motivation is:
Txt2tags has a very straight way of growing, following basic concepts. These are the highlights:
Source File Readable | Txt2tags marks are very simple, almost natural. |
Target Document Readable | The target document is also readable, with indentation and spacing. |
Consistent Marks | Txt2tags marks are simple symbols, designed to be unique enough to don't mix up with the document contents. |
Consistent Rules | 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 are simple, with no extra-options or complicated behavior modifiers. A mark is just a mark, with no options at all. |
Easy to Learn | With simple marks and readable source, the txt2tags learning curve is user friendly. |
Nice Examples | The sample files included on the package gives real life examples of documents written for txt2tags. |
Valuable Tools | The syntax files included on the package help you to write documents with no syntax errors. |
Three User Interfaces | There is a user friendly Graphical interface, a handy Web interface easy to install in intranets and a Command Line interface for power-users and scripting. |
Scripting | With the full featured command line mode, an experienced user can automatize tasks and do post-editing 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 Macs. |
Mature | 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. |
Absolutely NO!
It's free, GPL licensed.
The following is a list of all the structures supported by txt2tags.
startx -- -bpp 8
), the presentation will look pretty!
The key is: convert and use. No quick fixes or requirements needed.
{{{'''''adding braces and quotes'''''}}}
, so txt2tags comes with the
simplified marks and unified solution: one source, multi targets.
Tip: Use the --targets
command line option to get a complete list of
all the available targets.
Structure | html | xhtml | sgml | dbk | tex | lout | man | mgp | creole | wiki | gwiki | pmw | doku | moin | pm6 | adoc | art | txt |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
headers | Y | Y | Y | Y | Y | Y | Y | Y | - | - | - | Y | - | - | N | - | Y | Y |
section title | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
paragraphs | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
bold | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - |
italic | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - |
underline | Y | Y | - | Y | Y | Y | - | Y | - | Y | - | Y | Y | Y | Y | N | - | - |
strike | Y | Y | N | N | Y | - | - | - | - | Y | Y | Y | Y | Y | N | N | - | - |
monospaced font | Y | Y | Y | Y | Y | Y | - | Y | - | Y | Y | Y | Y | Y | Y | Y | - | - |
verbatim line | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - |
verbatim area | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | - | - |
quoted area | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | N | Y | Y |
internet links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - |
e-mail links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - |
local links | Y | Y | Y | Y | N | N | - | - | N | N | N | Y | Y | Y | - | N | - | - |
named links | Y | Y | Y | Y | - | - | - | - | Y | Y | Y | Y | Y | Y | - | Y | - | - |
bulleted list | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
numbered list | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
definition list | Y | Y | Y | Y | Y | Y | Y | N | Y | Y | - | Y | - | Y | N | N | Y | Y |
horizontal line | Y | Y | - | N | Y | Y | - | Y | Y | Y | - | Y | Y | Y | N | N | Y | Y |
image | Y | Y | Y | Y | Y | Y | - | Y | Y | Y | Y | Y | Y | Y | N | Y | - | - |
table | Y | Y | Y | N | Y | N | Y | N | Y | Y | Y | Y | Y | Y | N | N | N | N |
Extras | html | xhtml | sgml | dbk | tex | lout | man | mgp | creole | wiki | gwiki | pmw | doku | moin | pm6 | adoc | art | txt |
image align | Y | Y | N | N | N | Y | - | Y | N | Y | - | N | Y | N | N | N | - | - |
table cell align | Y | Y | Y | N | Y | N | Y | N | N | N | - | N | - | Y | N | N | N | N |
table column span | Y | Y | N | N | N | N | N | N | N | N | - | N | - | N | N | N | N | N |
Legend | |
---|---|
Y | Supported |
N | Not supported (may be in future releases) |
- | Not supported (can't be done on this target) |
As different users have different needs and environments, txt2tags is very flexible on how it runs.
There are three User Interfaces for the program, each one with its own purpose and features.
Since version 1.0, there is a nice Graphical Interface, that works on
Linux, Windows, Mac and others. Just call txt2tags with the --gui
option to open it.
The interface is pretty simple and intuitive:
A nice option is the "Dump to screen", 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.
The default interface colors can be changed on the configuration file,
using the %!guicolors
settings. For example:
% set my own colors for the graphical interface (bg1, fg1, bg2, fg2) %!guicolors: blue white brown yellow
The Web Interface is up and running on the Internet at http://txt2tags.org/online.php, so you can use and test the program instantly, before download.
One can also put this interface on the local intranet avoiding to install txt2tags in all machines.
For command line power users, the --help should be enough:
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.
Please read the txt2tags man page for detailed information about options and command line use.
Examples:
Convert to 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 |
And also, numbering titles | $ txt2tags -t html --toc --enum-title file.t2t |
. | |
Contents quick view | $ txt2tags --toc-only file.t2t |
Maybe enumerate them? | $ txt2tags --toc-only --enum-title file.t2t |
. | |
One liners from STDIN | $ echo -e "\n**bold**" | txt2tags -t html --no-headers - |
Testing Mask Email feature | $ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers - |
Just download the program and run it on your machine.
First of all, you must download and install Python on your system. Txt2tags requires Python version 2.2 or newer.
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.
If you are not sure if you have Python or not, open a console (tty,
xterm, MSDOS, Terminal.app) and type python
. If it is not installed, the system
will tell you.
The official location for txt2tags distribution is on the program site, at http://txt2tags.org. Just download and uncompress the package (.tgz file).
If you're in Linux, you can also use the automatic installer of your system. Some examples:
As a single Python script, txt2tags needs no installation at all.
The only file needed to use the program is the txt2tags script. The other files of the package 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 the txt2tags script to a system PATH directory and make sure the system knows how to run it.
chmod +x txt2tags
) and copy it to a
$PATH directory (cp txt2tags /usr/local/bin
)
C:\Windows\System32
.
After that, you can create an icon on your desktop for it, if you want to use the program's Graphical Interface.
Txt2tags comes with handy syntax highlighting files to be used by the following text editors:
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.
![]() |
Sample file opened in Vim Editor |
Each editor has a different install procedure for a syntax highlighting file, please read the syntax file headers and the editor documentation.
To make the first conversion you will need three things: txt2tags, a text editor and a web browser.
python /path/to/txt2tags
or even
/path/to/python /path/to/txt2tags
if Python is not on your PATH.
txt2tags --gui
.
If everything went right, you should be seeing a three line document with this contents:
My First Document A txt2tags test Sunday, 2004
This is just a part of the document, but we can already convert it and check the results.
Now save this document with the name test.txt
. Remember to save it
as plain text. Pay attention to which folder you are saving the file,
you will need to remember it soon.
If you are in the Command Line Interface, please skip this step and read the next one.
If you are in the Gui Interface, follow this steps:
test.txt
you just saved
(remember the folder!).
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.
If you are in the Command Line Interface, move to the folder where the file was saved and type this command:
txt2tags --target html test.txt
The option --target
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.
The results were saved to the test.html
file and then the program will show you the
"txt2tags wrote test.html" message.
If some error occurred, read the message carefully.
Here is a sample of how it will be shown on your screen:
prompt$ txt2tags --target html test.txt txt2tags wrote test.html prompt$
Open the test.html
file on the web browser to check if everything
is ok.
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.
You write text, txt2tags does the rest ;)
Tip: You can also use CSS files on HTML pages generated by txt2tags, so the page appearance is 100% configurable.
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.
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.
Considering the following contents for the test.txt
file, which is
only plain text, compare the generated HTML page:
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
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.
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,
**stars for bold**
and == equals for title ==
. You can learn the
marks on the Txt2tags Markup Demo.
Txt2tags marked files are divided in 3 areas. Each area have its own rules and purpose. They are:
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.
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:
____________ | | | HEADERS | 1. First, the Headers | | | CONFIG | 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. |
Config | 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 Header Area. |
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.
Location:
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.
These lines are content-free, with no static information type needed. But the following is recommended:
%%date
)
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.
Sometimes the user wants to specify less than three lines for headers, giving just the 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.
No headers on the document is often useful if you want to specify your
own customized headers after converting. The command line option
--no-headers
is usually required for this kind of operation.
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:
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.
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.
Please read the Settings section for more information about them.
Location:
The body is anything outside Headers and Config Areas.
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 --no-headers
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.
Settings are special configurations placed at the source document's Config Area that can affect the conversion process. Their syntax is:
%! keyword : value
List of valid keywords:
Keyword | Description |
---|---|
Target | Set the default target to the document be converted to. |
Options | Set the default options to be used on the conversion. The format is the same as the command line options. |
Style | Set the document style. Used to define a CSS file for HTML/XHTML and to load a package in LaTeX. |
Encoding | Set the document Character Set. Used if the document contains accented letters or other not-ASCII characters. |
PreProc | Input filter. Sets "find and replace" rules to be applied on the Body Area of the source document. |
PostProc | Output filter. Sets "find and replace" rules to be applied on the converted document. |
Example:
%!target : html %!options : --toc --toc-level 3 %!style : fancy.css %!encoding: UTF-8 %!preproc : "AMJ" "Aurelio Marinho Jargas" %!postproc: '<BODY.*?>' '<BODY bgcolor="yellow">'
Note that the spacing and capitalization of the keyword are ignored. So you can also do %!Target:html
and %! TARGET :html
.
Learn more about settings in Part VII - Mastering Settings.
The fastest way of changing the txt2tags default behavior is to use command line options. This options are available on the Command Line Interface only, not on Gui or Web.
Just like the other system's tools, the program do accept a set of
predefined options. An option is an hyphen followed by a letter or two
hyphens followed by one or more words, like -t
and --target
.
Options that are generally used are --outfile
to define a customized
output file name, --toc
to turn on the automatic TOC generation and
--encoding
to set the document character set. Most of the options
can be turned off prefixing a "no-" before its name, for example:
--no-encoding
and --no-toc
.
You can register the desired options for a source file inside its
Config Area, using the %!options
setting. This way you don't have to
type them on the command line anymore.
Example:
%!options: --toc -o mydoc.html
The exception is the target specification, that has its own setting:
%!target: html
Use the --help
option to get a complete list of all the options
available in txt2tags.
Learn more about %!options and %!target.
The user configuration file (also called RC file) is a central place to store the settings that will be shared by ALL converted files. If you keep inserting the same settings on every .t2t file you write, move it to the RC file and it will be used globally, for existing and future source files.
The default location of this file depends on your system. It can also be specified by the user, using an environment variable.
RC file location | |
---|---|
Windows | %HOMEPATH%\_t2trc |
UNIX, Linux, Mac | $HOME/.txt2tagsrc |
User defined | T2TCONFIG variable |
The format of the settings is exactly the same as the ones used on the
.t2t files Config Area. There is a sample RC file on the package at
doc/txt2tagsrc
. Example:
% my configs %%% Always use CSS-friendly tags in HTML %!options(html): --css-sugar %%% Change the default TOC depth for all targets %!options: --toc-level 4 %%% Set the default encoding for all documents %!options: --encoding UTF-8
Any line that is not blank, a comment or a valid config line will raise error when txt2tags runs. So be careful when editing this file.
Txt2tags automatically apply the RC file contents into any source file it
is converting. If you want to disable this behavior for a specific
file, use the --no-rc
command line option.
There are three ways of telling txt2tags which options and settings to use, and this is the order that they are read and applied:
First txt2tags reads the RC file contents (if any) and apply its configurations on the current source file. Then it scans the source document Config Area for settings and if found, they are applied also, overriding the RC ones in case of conflict. Finally comes the command line options, stronger than the other two.
So, if the document encoding was defined on the three resources, the command line will be the one used.
The include
command is used to paste the contents of an external
file into the source document body. It is not a config, but a command,
and it is valid on the document Body Area.
The include
command is useful to split a large document into smaller
pieces (like chapters in a book) or to include the full contents of an
external file into the document source. Sample:
My first book Dr. John Doe 1st Edition %!include: intro.t2t %!include: chapter1.t2t %!include: chapter2.t2t ... %!include: chapter9.t2t %!include: ending.t2t
You just inform the filename after the %!include
string. The
optional target specification is also supported, so this is valid
either:
%!include(html): file.t2t
Note that include will insert the file Body Area into the source document. The included file Header and Config Areas are ignored. This way you can convert the included file alone or inside the main document.
But there's another three types of include:
The Verbatim type includes a text file preserving its original spaces and formatting, just like if the text was inside the txt2tags Verbatim area (```). To specify this type, enclose the filename with backquotes:
%!include: ``/etc/fstab``
The Raw type includes a text file as is, not trying to find and parse txt2tags marks on it, just like if the text was inside the Raw area ("""). To specify this type, enclose the filename with double quotes:
%!include: ""nice_text.txt""
And the Tagged type is passed directly to the resulting document, with NO parsing or escaping performed by txt2tags. This way you can include additional tagged parts to your document. Useful for default header or footer information, or more complicated tagged code, unsupported by txt2tags:
%!include(html): ''footer.html''
Note that the filename is enclosed with single quotes. As the text inserted is already parsed, you should specify the target to avoid mistakes.
The includeconf
command is used to include configurations from an
external file into the current one. This command is valid inside the
source document Config Area only.
It is useful to share the same config for multiple files, so you can
centralize it. On any file do you want to include that central
configuration, put a includeconf
call. Example:
My First Document John Doe July, 2004 %!includeconf: config.t2t Hi, this is my first document.
The format inside the included file is the same as in the RC file.
Note that the optional target specification is NOT supported for this command.
%!includeconf: config.t2t <--- OK %!includeconf(html): config.t2t <--- NOT OK
Overview of all txt2tags marks:
Basic | Beautifiers | ||
---|---|---|---|
Headers | First 3 lines | Bold | **words** |
Title | = words = | Italic | //words// |
Numbered title | + words + | Underline | __words__ |
Paragraph | words | Strike | --words-- |
Links | [label url] | Monospaced | ``words`` |
Image | [filename.jpg] | Raw text | ""words"" |
Tagged text | ''words'' | ||
Other | |||
Quote | <TAB>words | Separator line | |
List | - words | Strong line | ============... |
Numbered list | + words | Table | | cell1 | cell2 | cell3... |
Definition list | : words | Anchor | = title =[anchor] |
Comment line | % comments | Comment area | %%%\n comments \n%%% |
Verbatim line | ``` word | Verbatim area | ```\n lines \n``` |
Raw line | """ words | Raw area | """\n lines \n""" |
Tagged line | ''' words | Tagged area | '''\n lines \n''' |
General Rules:
=like this=
=title=
, ==subtitle==
,
===subsubtitle===
, ...
=====like this=====
=like this===
= like this =
=like this=[anchor]
. To link to an anchor
create a [local link #anchor]
% like this
%%%
, followed by
text lines, followed by another line with exactly 3 consecutive
percents %%%
**like this**
//like this//
__like this__
--like this--
** this ** is invalid
**%%date**
""**__like__ //this//**""
``like this``
`` this `` is invalid
""**
monobold**""
. The same applies to the other beautifiers
such as ""//
italic//""
and ""__
underline__""
.
""`
"" like this``
```
, followed by
text lines, followed by another line with exactly 3 consecutive
backquotes ```
www.likethis.com
[click here www.url.com]
[[image.jpg] www.url.com]
[see source %%infile]
[mirror of %%outfile www.url.com]
[likethis.jpg]
[likethis!~1.jpg]
[report-%%date(%Y-%m-%d).png]
[like this.jpg]
[ likethis.jpg ]
[LEFT.jpg]
blablablabla
[CENTER.jpg]
blablablabla
[RIGHT.jpg]
| table | row | with | five | columns |
""like this""
""" like this
''like this''
''' like this
''<br>''
,
custom DIVs ''<div id="myfooter">''
or even full blocks of code,
like the Google Analytics tracking code.
Macros are special purpose keywords, that are expanded on conversion time. They are used to insert dynamic information, for example the current date or information about the document source.
A macro is represented by the %%
chars followed by its name, such as
%%date
. Some macros do accept an optional formatting string inside
parenthesis, right after the macro name, such as %%date(%Y-%m-%d)
. This
format string mixes common text with special directives, identified by a
percent sign % followed by an identification character. If no format
string is given, the default format is used.
Macro Name | Expands to... | Default Format |
---|---|---|
%%date | The current date | %Y%m%d |
%%mtime | The source file modification time | %Y%m%d |
%%infile | The source file path | %f |
%%outfile | The output file path | %f |
%%toc | The document TOC (Table of Contents) | - |
General rules:
%%date
, %%DaTe
and
%%DATE
are identical
Full example (bold text are expanded macros):
This is the Txt2tags User Guide, converted to html by txt2tags from the userguide.t2t source file. The conversion was done at 2010-10-21 21:04:29, but the last change on the source document was made on 2010-10-21 21:04:25. Both source and converted file reside on the userguide directory.
The %%date
macro expands to the current date and time. It is very
useful on the document headers or footer, to register the date when the
document was generated. To expand to the source document last
modification time, see the %%mtime macro.
This macros accepts several formatting directives. The full list can be found in the Python site. Here are the most commonly used:
Directive | Description |
---|---|
%a | Locale's abbreviated weekday name. |
%A | Locale's full weekday name. |
%b | Locale's abbreviated month name. |
%B | Locale's full month name. |
%c | Locale's appropriate date and time representation. |
%d | Day of the month as a decimal number [01,31]. |
%H | Hour (24-hour clock) as a decimal number [00,23]. |
%I | Hour (12-hour clock) as a decimal number [01,12]. |
%m | Month as a decimal number [01,12]. |
%M | Minute as a decimal number [00,59]. |
%p | Locale's equivalent of either AM or PM. |
%S | Second as a decimal number [00,61]. (1) |
%x | Locale's appropriate date representation. |
%X | Locale's appropriate time representation. |
%y | Year without century as a decimal number [00,99]. |
%Y | Year with century as a decimal number. |
%% | A literal "%" character. |
Examples:
Macro | --> | Results for on 2010, Oct 21 at 21:04 |
---|---|---|
%%date(Converted on: %c) | --> | Converted on: Thu Oct 21 21:04:29 2010 |
%%date(%Y-%m-%d) | --> | 2010-10-21 |
%%date(%I:%M %p) | --> | 09:04 PM |
%%date(Today is %A, on %B.) | --> | Today is Thursday, on October. |
The %%mtime
macro expands to last modification time of the source
document. It is useful to register when the file was last changed.
This macro is a "sister" of the %%date macro, so it
accepts exactly the same formatting directives.
As an example, this User Guide source file was last edited on
Thu Oct 21 21:04:25 2010. This date was expanded from %%mtime(%c)
.
The %%infile
macro expands to the source file location on the
system. It is useful to make those "see the source of this file"
links on HTML pages. Providing such link is a friendly attitude with
beginners, so they can use your source as a sample for their own page.
This macro accepts the following formatting directives:
%<char> | Description | Output for this User Guide source |
---|---|---|
%f | File name | userguide.t2t |
%F | File name (without extension) | userguide |
%e | File extension | t2t |
%p | Absolute file path | /a/txt2tags/svn/doc/English/userguide/userguide.t2t |
%d | File path (directories only) | /a/txt2tags/svn/doc/English/userguide |
%D | File path (parent dir only) | userguide |
%% | Literal percent char | % |
Examples:
Source | --> | Expanded |
---|---|---|
This Guide parent dir is %%infile(%D). | --> | This Guide parent dir is userguide. |
I do use the %%infile(%e) file extension. | --> | I do use the t2t file extension. |
[See the source %%infile] | --> | See the source |
Converted to XHTML, I'll be %%infile(%F).xhtml | --> | Converted to XHTML, I'll be userguide.xhtml |
Note: The macro is expanded to "-" if the source file is STDIN.
The %%outfile
macro expands to the converted file location on the
system. It is useful to its name inside the document Body or Headers.
This macro is a sister of the %%infile macro and
do accept exactly the same formatting directives.
Examples:
Source | --> | Expanded |
---|---|---|
You are reading the %%outfile file. | --> | You are reading the userguide.html file. |
txt2tags -t %%outfile(%e) -i %%infile -o %%outfile | --> | txt2tags -t html -i userguide.t2t -o userguide.html |
Note: The macro is expanded to "-" if the output file is STDOUT.
The %%toc
macro expands to the document's Table of Contents. It is
useful for you to specify exactly where you want the TOC to be placed.
You can even use the macro more than one time and place the TOC at the
end of the document also, for example. This Guide is using %%toc
to position the TOC.
Different from the other macros, this one does not accept a format string and has its own special rules:
Settings are special configurations placed at the source document's Config Area that can affect the conversion process. The Settings are all optional. The average user can live fine without them. But they are addictive, if you start using them, you'll never stop :)
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 by a colon (":").
%! keyword : value
Syntax details:
Rules:
Using the target setting, a default target format is defined for the document:
%!target: html
This way the user can just call
$ txt2tags file.t2t
And the conversion will be done, to the specified target.
The target setting does not support optional target specification.
That doesn't make sense, such as %!target(tex): html
.
Writing long command lines every time you need to convert a document is boring and error prone. The Options setting let the user save all the converting options together with the source document. This also ensures that the document will always be converted the same way, with the same options.
Just write it with no syntax errors, as you were on the real command line. But omit the "txt2tags" program call on the beginning, the target specification and the source filename from the ending.
For example, if you do use this command line to convert your document:
$ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t
You can save yourself from typing pain using this Options setting inside the document source:
%!target: html %!options(html): --toc --toc-level 2 --enum-title
Now the options are registered inside the source file, so you can convert it with this simple command:
$ txt2tags file.t2t
Tip for Vim users: To convert the document right inside the editor, just run :!txt2tags %
The Encoding setting is needed by non-english writers, who uses accented letters and other locale specific details, so the target document Character Set must be customized (if allowed).
The valid values for the Encoding setting are the same charset names valid for HTML documents, like iso-8859-1 and koi8-r. If you're not sure which encoding you should use, try utf-8. If that doesn't work, this complete (and long!) list should help.
The LaTeX target uses alias names for encoding. This is not a problem for the user, because txt2tags translate the names internally. Some examples:
txt2tags/HTML | > | LaTeX |
---|---|---|
windows-1250 | >>> | cp1250 |
windows-1252 | >>> | cp1252 |
ibm850 | >>> | cp850 |
ibm852 | >>> | cp852 |
iso-8859-1 | >>> | latin1 |
iso-8859-2 | >>> | latin2 |
koi8-r | >>> | koi8-r |
If the value is unknown to txt2tags, it will be passed "as is", allowing the user to specify custom encodings.
The PreProc is an input filter that changes the Body Area of the source document. It is a "find and replace" feature, applied right after the line is read from the document source, before any parsing by txt2tags.
It is useful to define some abbreviations for common typed text, as:
%!preproc: JJS "John J. Smith" %!preproc: RELEASE_DATE "2003-05-01" %!preproc: BULLET "[images/tiny/bullet_blue.png]"
So the user can write a line like:
Hi, I'm JJS. Today is RELEASE_DATE.
And txt2tags will "see" this line as:
Hi, I'm John J. Smith. Today is 2003-05-01.
This filter is a component that acts between the document author and the txt2tags conversion. It's like a first conversion before the "real" one. This behavior is similar to an external Sed/Perl filter, called this way:
$ cat file.t2t | preproc-script.sh | txt2tags -
So the txt2tags parsing will begin after all the PreProc substitutions were applied.
Note: Remember that the preprocessing is applied only to the BODY of the source document, not including the Header Area and Config Area.
The PostProc is an output filter that changes the converted document. It is a "find and replace" feature, applied after all txt2tags parsing and processing is done.
It is useful to do some refinements on the generated document, change tags and add extra text or tags. Quick samples:
%!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">' %!postproc(tex) : "\\newpage" ""
These filters change the background color of the HTML page and remove the page breaks on the LaTeX target.
The PostProc rules are just like an external Sed/Perl filter, called this way:
$ txt2tags -t html -o- file.t2t | postproc-script.sh > file.html
Before this feature was introduced, it was very common to have little scripts to "adjust" the txt2tags results. These scripts were in fact just lots of sed (or alike) commands, to do "substitute this for that" actions. Now this replacement strings can be saved together with the document text, and the plus is to use the Python powerful Regular Expression machine to find patterns.
\usepackage
modules.
--style
.
All the settings (except %!target) can be glued with a specific target
using the %!key(target): value
syntax. This way user can define
different config for different targets.
This is specially useful in the pre/postproc filters, but is applicable to all settings. For example, defining different styles for HTML and LaTeX:
%!style(html): fancy.css %!style(tex) : amssymb
For the options setting it's very useful to adjust the converted document:
%!target: sgml %!options(sgml): --toc %!options(html): --style foo.css %!options(txt ): --toc-only --toc-level 2
In this example, the default target is Sgml and it will use TOC. If the
user run txt2tags -t html file.t2t
, only the HTML options will be
used, so the converted file will use "foo.css" style file and will
have no TOC.
%!postproc : this that %!postproc(html): that other
\n
(line break) and \t
(tabulation) are
interpreted
%!postproc: "undesired string" ""
%!postproc(target): <this> <that>
$ cat file.t2t | preproc.sh | txt2tags | postproc.sh
\* \+ \. \^ \$ \? \( \) \{ \[ \| \\
%!postproc(html): '(</?)B>' '\1STRONG>'
%!postproc: PATT REPLACEMENT %!postproc: "PATT" "REPLACEMENT" %!postproc: 'PATT' 'REPLACEMENT' %!postproc: PATT "REPLACEMENT" %!postproc: "PATT" 'REPLACEMENT'
This chapter is really not recommended for newbies. It demonstrates how to do strange things with txt2tags filters, abusing of complex patterns and Regular Expressions.
BEWARE! The following procedures are NOT encouraged and can break things. Even some text from the document source can be lost on the conversion process, not appearing on the target document. Just use these tactics if you really need them and know what you are doing.
Note: Filters are a powerful feature, but can be dangerous!
Note: Bad filters do generate unexpected results.
Keep that in mind, please.
In filters, the replacement pattern can include multiple lines using the
\n
line break char.
This can be handy for including really short CSS rules on HTML target, with no need to create a separate file:
%!postproc: <HEAD> '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>' %!postproc: (</STYLE>) 'body { margin:3em ;} \n\1' %!postproc: (</STYLE>) 'a { text-decoration:none ;} \n\1' %!postproc: (</STYLE>) 'pre,code { background-color:#ffffcc ;} \n\1' %!postproc: (</STYLE>) 'th { background-color:yellow ;} \n\1'
All the filters are tied to the first one, by replacing a string that it has inserted. So a single "<HEAD>" turns to:
<HEAD> <STYLE TYPE="text/css"> body { margin:3em ;} a { text-decoration:none ;} pre,code { background-color:#ffffcc ;} th { background-color:yellow ;} </STYLE>
Sometimes you need to insert some text on a specific target, but not on the others. This kind of strange behavior can be done using some PreProc tricks.
The idea is to insert this extra text on the document source as comments, but mark it in a way that a target-specific filter will "uncomment" those lines.
For example, if an extra paragraph must be added only in HTML target. Place the text as special comments, like this:
%html% This HTML page is Powered by [txt2tags http://txt2tags.org]. %html% See the source TXT file [here source.t2t].
As those lines start with %
, they are plain comments lines and will be
ignored. But when adding this special filter:
%preproc(html): '^%html% ' ''
The leading string is removed and those lines will be "activated", not being comments anymore. As a explicit target config, this filter will be processed for HTML targets only.
Being a Regular Expressions guru, the user can customize the document source syntax, changing the txt2tags default marks to some he find more comfortable.
For example, a leading TAB is the Quotation mark. If the user doesn't like it, or his text editor has some strange relationship with TABs, he can define a new mark for Quoted text. Say a leading ">>> " was his choice. Then he will do this simple filter:
%!preproc: '^>>> ' '\t'
And on the document source, the quoted text will be something like:
>>> This is a quoted text. >>> The user defined this strange mark. >>> But they will be converted to TABs by PreProc.
Before the parsing begins, the strange ">>> " will be converted to TABs and txt2tags will recognize the Quote mark.
BEWARE! Extreme PreProc rules could eventually change the entire marks syntax, even generating conflicts between marks. Be really really careful when doing this.
Thanks for reading! :)