How to add a new target to txt2tags

It's easy!

% Bypass site autotag for {{...}} that turns to <...> in diff output
%!postproc: '{{( *\\a *)}}'	{@\1@}

%!includeconf: config.t2t

% Undo the bypass
%!postproc: {@(.*?)@}	{{\1}}

%!postproc: '(?i)(<body)'	'\1 id="new-target"'
%!options: --toc --toc-level 1

% Trick to make bold inside verbatim
%!postproc: @@@(.*?)@@@	<b>\1</b>

% Trick to color the diff output
%!postproc: ^(\+.*)	<span style="font-weight:bold;color:green">\1</span>
%!postproc: ^(-.*)	<span style="font-weight:bold;color:red">\1</span>

%!include: menu.t2t

== Yes, YOU can make it ==

So you like txt2tags very much but your favorite format is not yet supported? How about adding it yourself?

You don't need to be a Python programmer to do it. You'll just define variables, no algorithm is needed. In fact, if text editors and the command line don't scare you, **you don't even need to be a programmer** to do it. Just read this document carefully :)

On the following guidelines we'll add the imaginary "foo" target to txt2tags.

%%TOC

+ Get the most recent txt2tags source code +

IMPORTANT!

Before you start, make sure you have the newest txt2tags code, available at http://txt2tags.googlecode.com/svn/trunk/txt2tags

Open this file on your favorite text editor.

+ Add the target identifier in TARGETS +

% This step can be removed by TARGET = TARGET_NAMES.keys()
% But the ordering of TARGET is important to the --help and Tk interface menus
% Think about it

At the beginning of the txt2tags source code, right after the long heading comments, you'll find the declaration of all the available targets:

``` TARGETS = 'html xhtml sgml tex lout man mgp wiki gwiki doku moin pm6 txt'.split()

Just add your new target identifier. Choose a short name (5 letters or less).

``` TARGETS = 'html xhtml sgml tex lout man mgp wiki gwiki doku moin pm6 txt @@@foo@@@'.split()

	Note: This identifier will also be the filename extension used by txt2tags when saving the result to a file.

You can already run "./txt2tags --help" and see your new target listed on the --target option!

+ Add the textual description in TARGET_NAMES +

Scroll down a little and you'll find the target names. Add a new item to the dictionary, using your identifier and the textual description of it:

```
TARGET_NAMES = {
  'html' : _('HTML page'),
  'xhtml': _('XHTML page'),
  'sgml' : _('SGML document'),
  'tex'  : _('LaTeX document'),
  'lout' : _('Lout document'),
  'man'  : _('UNIX Manual page'),
  'mgp'  : _('MagicPoint presentation'),
  'wiki' : _('Wikipedia page'),
  'gwiki': _('Google Wiki page'),
  'doku' : _('DokuWiki page'),
  'moin' : _('MoinMoin page'),
  'pm6'  : _('PageMaker document'),
  'txt'  : _('Plain Text'),
  @@@'foo'  : _('FOO Document'),@@@
}
```

	Tip: Copy & paste instead writing from zero to make sure you won't forgot the _(...) format.

+ Add the header template in HEADER_TEMPLATE +

The headers are the first three lines of a txt2tags document. Some targets as LaTeX have a specific place for them (the Preamble), others don't. Make a decision on how to format the header lines. You have three tokens available:

- **%(HEADER1)s** - The first source line (Document title)
- **%(HEADER2)s** - The second source line (Document author)
- **%(HEADER3)s** - The third source line (Document date)
-

The title/author/date contents are just suggestions. The user can put whatever he/she wants at those lines. And remember that while the first line (title) is required, the other two are optional. Their lines at this template will be removed if not present.

```
  '@@@foo@@@': """\
@@@<title-tag>@@@%(HEADER1)s@@@</title-tag>@@@

@@@<author-tag>@@@%(HEADER2)s@@@</author-tag>@@@

@@@<date-tag>@@@%(HEADER3)s@@@<date-tag>@@@
""",
```

	Tip: Once again, copy & paste instead writing from zero.

	Tip: To show a literal "%" use "%%".

+ Add the target's tags in getTags() +

This is the most tricky step. Some targets are easy, some are more exotic.

First, find the definition of the getTags() function.

``` def getTags(config):

The **keys** variable stores all the valid tokens you can use to describe your target's tags.

The **alltags** dictionary stores the tags for each target. This is where you'll add your new target.


```
'@@@foo@@@': {
   'title1'              : '@@@<title-tag-1>@@@\a@@@</title-tag-1>@@@' ,
   'title2'              : '@@@<title-tag-2>@@@\a@@@</title-tag-2>@@@' ,
   'title3'              : '@@@<title-tag-3>@@@\a@@@</title-tag-3>@@@' ,
   ...
},
```

	Tip: The easiest is to find and already added target that is similar to yours, copy & paste the code and modify it. Don't start from zero.

Note the "\a" on the tags. It represents the text the user typed inside that mark. So "=My Title=" will be converted to "<title-tag-1>**My Title**</title-tag-1>".

You can also put a "\n" character to represent a line break. It's useful if your tag spans in multiple lines. A Tab can be inserted using "\t".

At this point you can already run a "txt2tags -t foo sample.t2t" command and it will work! The results will be saved to sample.foo. Check it out.

	Tip: Keep editing and running to adjust and improve your target support.

+ Add the target's rules in getRules() +

This is the final step. Besides the tags already added, now you can also specify some rules to fine-tune your target code.

Search for the function definition:

``` def getRules(config):

Then read carefully the **allrules** comments to learn which options are available.

Once again, copy & paste the entry of an already added tag to make your life easiest. Put there all the rules you need, always using 1 as the value. You don't need to turn off a rule with zero. Just don't mention it and it will be disabled by default. In other words, just add the rules you want to be ON.

```
'@@@foo@@@' : {
  'indentverbblock':1,
  'spacedlistitem':1,
  'parainsidelist':1,
  'keeplistindent':1,
  'barinsidequote':1,
  'autotocwithbars':1,
  'blankendmotherlist':1,
  },
```

And that's it! Now your target is fully added to the txt2tags program!

+ Send me your work! +

Once you're done, [send me your work http://aurelio.net/img/emeio.png] so I can include it on the official txt2tags source and everybody can use your target. You will also be included on the [Team page team/] and your karma will increase in 2,715 points :)

The only file you must e-mail me is the full txt2tags code modified with your target.

**Have a good programming time!**

= A real-world example =

See how easy it was to add the DokuWiki target to txt2tags. This file is in the diff format, where red lines are OLD and green lines are NEW:

%!include: ``doku-adding.diff``

%!include: footer.t2t