# txt2tags Upgrade Guide: from 1.x to 2.0

### July, 2004

# 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.

- Marks must be glued with the contents, no boundary spaces

      ** bold **    --->   NOT bold
      **bold**      --->   bold OK

- Marks are greedy, always getting as must as they can (just like .* in Regular Expressions):

      ****bold****  --->   <b>**bold**</b>

## 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.