About

This document is intended for those who already use txt2tags version 1.7 or older, and has some .t2t files written. If you never used the program, don't mind reading it.

Intro

First of all, thank you for being a txt2tags user. The program would not exist without all the user support.

The new txt2tags 2.0 version starts a new development cycle of the program. Lots of innovations were made since the last 1.7 version.

To make sure the program will keep evolving, some design decisions had to be made. As a result, there are changes on command line options, settings and marks, so v2.0 BREAKS BACKWARDS COMPATIBILITY.

Your old .t2t files may NOT work as expected.

This document details all the changes that do affect the already existent .t2t files. Read it with attention before upgrade.

The t2tconv tool

To help you on the upgrade, there is a handy t2tconv tool on the v2.0 tarball. It converts your .t2t files to the new format.

It is a Python script, so run it the same way you run txt2tags. Considering it is on the environment PATH, for most systems it is just: 

t2tconv file1.t2t file2.t2t ...

The original file is saved with the .old extension. Just run it once for all your existing .t2t files.

This is a sample old ancient.t2t file: 

My ancient document
John Doe
Summer, 2004

%!cmdline: -t html --noheaders

Hi, today i am  */really/* happy, i've installed `txt2tags` here.

And now see t2tconv in action: 

prompt$ t2tconv -n ancient.t2t
File ancient.t2t has 5 fixes to be made
prompt$

Use the -n command line option if you just want a report if the file has some changes to be made or not. The file is NOT changed. 

prompt$ t2tconv -n -v ancient.t2t
+ [line 0006] Added %!target from old %!cmdline
+ [line 0006] Old --noheaders option changed to --no-headers
+ [line 0006] Old %!cmdline setting changed to %!options
+ [line 0008] Old */bolditalic/* mark is dead, now using **//bold+italic//**
+ [line 0008] Old `verb` inline mark changed to ``verb``
File ancient.t2t has 5 fixes to be made
prompt$

Add the -v command line option if you want a detailed report of the changes to be made.

With no options, the file is converted: 

prompt$ t2tconv ancient.t2t
Rewritten ancient.t2t (5 fixes) - backup saved as ancient.t2t.old
prompt$

And now ancient.t2t is upgraded to be used with txt2tags v2.0: 

My ancient document
John Doe
Summer, 2004

%!target: html
%!options: --no-headers

Hi, today i am  **//really//** happy, i've installed ``txt2tags`` here.

The Changes

Old %!cmdline setting splitted into %!target and %!options

There is no %!cmdline setting anymore. The default options are now specified with %!options. And the default document target is now specified with %!target.

Version 1.7: 

%!cmdline: -t html --toc --toclevel 3

Version 2.0: 

%!target: html
%!options(html): --toc --toc-level 3

If multiple %!target were given, only the last one will be used. If multiple %!options were given, all of them will be used, in sequence (they are cumulative).

Definition list mark

The definition list is now specified with the <colon><space> prefix. Oneliners are not valid anymore, as old "= term: description" were.

Version 1.7: 

= banana: yellow tropical fruit

Version 2.0: 

: banana
yellow tropical fruit

Image centralizing

To make an image centralized, we used to let is alone in a paragraph. Now it is necessary make it clearer, placing at least one space before and other after it.

Version 1.7: 

<start-of-line>[image.jpg]<end-of-line>

Version 2.0: 

<start-of-line><space>[image.jpg]<space><end-of-line>

New rules for beautifiers

There are new rules used to recognize a valid beautifier. Beautifiers are: bold, italic, underline and monospaced text.

Mark for bolditalic was removed

There is no mark for bolditalic anymore. Just use the italic mark together with the bold one to get the same behavior.

Version 1.7: 

*/bolditalic/*

Version 2.0: 

**//bolditalic//**

Changes on command line options

The --type has changed to --target and the dash was added to separate words, making it clearer to read. Here is the complete list:

version 1.7 version 2.0
type target
noheaders no-headers
enumtitle enum-title
maskemail mask-email
toclevel toc-level
toconly toc-only

Changes on marks

Type version 1.7 version 2.0
Monospaced text `text` ``text``
Raw text ``text`` ""text""
Verbatim text --- ```
Definition List = term: : term
Include text file %!include: `file.txt` %!include: ``file.txt``
Include tagged file %!include: 'file.html' %!include: ''file.html''

Okay

Now that you have read it all,

  1. Download the new version

  2. Change your existing .t2t files to the new format with the t2tconv command

  3. Convert your documents and check the results

  4. Enjoy!

And check out the "What's New" document also.

In doubt, please write to the program mailing list to get technical support.

TIP: Save the program as txt2tags2, so you can use both v1.7 and v2.0 at the same time in this transitional period.