2. Quick document tree

Writing a long document and suddenly get lost? Needs to edit that 50
page monster you don't touch for months? There is a quick way to get
an overview of the contents:

$ txt2tags --toc-only -t txt userguide.t2t
Part I - Introducing Txt2tags
The First Questions You May Have
Supported Formatting Structures
Supported Targets
Status of Supported Structures by Target
The Three User Interfaces: Gui, Web and Command Line
Part II - OK, I want it. Now what?
Download & Install Python
Download txt2tags
...

The --toc-only option dumps the Table of Contents of the document,
using the same target as the document's. So we force it to be clear
text with -t txt. Another option that can be used is
--enum-title to get nice numbers:

If you want to use this filter for all your files, put it on the txt2tags RC File.

4. Make case insensitive filters

PreProc and PostProc filters are case sensitive by default. This
means that when matching, the text "txt2tags" is different from
"TXT2TAGS". If you want to make a filter that treats lower and
uppercase letters as the same (ignore case), just put a "(?i)" at
the beginning. Example:

%preproc: '(?i)latex' 'LaTeX'

This way, "latex", "LATEX", "LAtex" and all its variants will be
changed to "LaTeX".

5. Make centred aligned paragraphs

In txt2tags you can't center paragraphs, but you can center a table.
So...

| This is a centered paragraph.

This line results in:

This is a centered paragraph.

Note: There are spaces before the pipe | to make the table centred. There
are no trailing pipe at the end of the line, so this table has no
border, making it invisible.

This site is powered by [txt2tags URLT2T]. For more information
please [read my Blog URLBLOG] or [search Google URLGOOGLE].

Compare this to the inline links (ugly) version:

This site is powered by [txt2tags http://txt2tags.org].
For more information please
[read my Blog http://myblog.wordpress.com/2006/10/31/foo-bar-baz]
or [search Google http://google.com?q=txt2tags+is+cool].

Plus: If there are links that you use all the time in your
documents (your website or blog, for example), you can make a global
link bank on an urls.t2t file, or on your
txt2tags RC File, then
all your documents can use them. The other advantage is that it makes
easy when the link changes, you just have to edit one single place.

7. Use automatic linking for "cristal clear" text

An evolution from the previous tip, you can put links automatically
for any word(s) you want.

Depending on the target, you may have to specify a new file encoding so that these symbols appear correctly. If you run into problems, try adding this line to your configuration:

%!encoding: iso-8859-1

The ™ symbol is a little trickier because it's part of the new UTF-8 encoding. First you need to save your source file as an UTF-8 text file. Check your text editor's preferences. Then just tell txt2tags about the new encoding:

%!encoding: utf-8

Bonus Tip: If you plan to type symbols or accented characters in your texts, a good practice is always use the UTF-8 encoding in your files. You don't need to understand exactly what it is, just keep in mind that is has all the symbols you may need someday :)

Another solution is to use the target's specific characters entities that represent those symbols. Then you can insert those symbols as "(C)", "(R)" and "(TM)" on the source file and let the filters do the dirty job. But remember that each target must have its own set of filters. An example for HTML:

Target Specific

14. Table COLUMN align targets: SGML, LaTeX and Man Page

Some targets let you align each table cell independently, as HTML.
Other are more strict, just letting you align the table column, then
all its cells share the same positioning. This is the case for SGML,
LaTeX and Man.

On this targets, the column alignment is defined by the align of the
first table row cells (usually it's a title row). So keep that in
mind when writing your text.

| Name | Age |
| John Smith | 55 |
| Mary Katana | 23 |

In this example, both columns will be centered on the aforementioned
targets, regardless the left and right align defined on the second and
third rows.

15. (X)HTML: What exactly the --css-sugar option does

It "insert CSS-friendly tags for HTML and XHTML targets" ;)

Ok, ok, more details:

The CELLPADDING attribute is removed from TABLE tag

The HR tags around Table of Contents (TOC) are removed

The Table of Contents is placed inside the new "toc" DIV

The page contents (except TOC) is placed inside the new "body" DIV

The PRE tag contents is not indented by two spaces

The headers (first three lines) are changed:

They are placed inside the new "header" DIV

They use H1, H2 and H3 tags with no formatting

So this option clears the formatting attributes and create new DIVs to
make it easier to use CSS rules. Then you can see the page as a three
piece component: header, toc, body and apply different rules for each.

Note: Using --style doesn't imply --css-sugar. You have to
declare both.

16. (X)HTML: Insert a manual line break <BR>

Txt2tags doesn't have a mark for the manual line break. In the cases
you want to use it, maybe a bullet list, a table or a verbatim text
would fit better.

But if the line break is the solution you want, just make your own new
mark for it. Let's say "@@" will be the line break mark.

So txt2tags will make the image tag <IMG SRC="RemoteImage.jpg">
and the filter will change it to <IMG SRC="http://www.example...">.

The other trick is cleaner to type, but relies on a txt2tags behavior
that may not work on future versions. Just protect the image address
with the raw mark, from the
beginning to the last character before the dot:

Hi, check out my picture: [""http://www.example.com/myimage"".jpg].

Easy!

20. (X)HTML: Insert text for images ALT attribute

Txt2tags already puts an empty ALT="" attribute on all images, so all
you have to do is to fill it. PostProc comes for the rescue.

%!postproc(xhtml): '(?i)(city.jpg.*?alt=")' '\1this is my city'
%!postproc(xhtml): '(?i)(beach.jpg.*?alt=")' '\1a really nice beach'
Hello, this is a photo of my city: [city.jpg]
And this the beach near here: [beach.jpg]

The PostProc rule is a
regular expression
that matches from the image filename until its ALT attribute contents
start. Don't worry if you don't understand these symbols. Just copy &
paste these lines to you text and change "city.jpg" by your image
filename and "this is my city" to the image's text. The rest remains
untouched.

21. (X)HTML: Insert custom tags (DIV, SPAN)

From txt2tags version 2.6 and newer, there's a new tagged mark to
directly insert target code.

You can do it in blocks:

'''
<div id="mycooldiv">
This paragraph will live inside mycooldiv DIV.
But note that txt2tags marks are not interpreted here.
</div>
'''

If you really need the entities, for some exotic reason or system limitation, you can convert the accented chars using filters. If you use just a few accented chars, create one filter for each letter (lower and uppercase):

Change the number "5" to the desired section number. Attention to the white spaces. Cut & paste this line to make sure it is correct.

If you want to use this filter for all your files, put it on the txt2tags RC File.

26. Man: Make the OPTIONS part of the man page

Man pages use a standard format to show a program's options. You can
make your man page looks exactly as the system's pages using
definition lists. Pay attention to the bold marks and leading spacing
on each definition term. Example:

= OPTIONS =
: **--dump-config**
print all the config found and exit
: **-h**, **--help**
print help information and exit
: **-V**, **--version**
print program version and exit

27. MagicPoint: Make a pause on the slide

You can use the strong bar (=========) to make a pause on the
current slide in MagicPoint. It's useful to show just the first part
of the slide, then you explain it, then you press the space bar and the
rest of the slide appears.

You can use as many pauses as needed, like one for each list item.
Example:

If you want to use this configuration for all your files, put it on the txt2tags RC File.

29. LaTeX: Remove the current date

In txt2tags, the third header line is often used for the document date. If you leave it blank, no date tag will be generated. But in LaTeX, when no date tag is found, it automatically shows the current date on the document cover. Some expect this behavior, some don't.

To force the document to have no date, you must leave an empty date tag on the LaTeX code: \date{}. You can make it easily setting a PostProc filter:

%!postproc(tex): \\date{-} \date{}

And in you source files, just type an hyphen on the third line, for example:

My doc
John Doe
-

The filter will remove the hyphen, leaving the tag empty and then LaTeX won't print any date.

Extra tip: If your TeX processor complains about the missing Author tag, you can do a similar workaround setting up another filter:

%!postproc(tex): \\author{-} \author{}

If you want to use this configuration for all your files, put it on the txt2tags RC File.

30. LaTeX: Set the language config (babel, inputenc)

For the text encoding (character set) just use the Encoding directive.
Then include the babel package in your document and create a PostProc
filter to insert the language for it. It's a three line wonder:

Note that the IANA standard encoding names are automatically
translated to the LaTeX equivalents
(iso-8859-1 to latin1 on this example).

31. LaTeX: Use a personal style file (.sty)

Create your own LaTeX user style file (say myrules.sty) with all the
packages and configuration you usually put inside the document
Preamble.

Then just use the Style directive pointing to your file. Remember to
include the relative path for the file, if it isn't on the same folder
as your txt2tags source file. The file must have the .sty
extension. You can use as many files as your heart wishes. Example: