txt2tags Upgrade Guide: from 1.x to 2.0

July, 2004

%!postproc: SITEROOT ..
%!includeconf: ../inc/config.t2t
%!options: --toc

%!postproc: (&lt;space&gt;)([^<]) '<b>\1</b>\2'
%!postproc: (prompt\$) '<b>\1</b>'

%!include: ../inc/menu.t2t

%%TOC

= 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,

+ [Download the new version SITEROOT/download.html]

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

+ Convert your documents and check the results

+ Enjoy!


And check out the ["What's New" document news.html] also.

In doubt, please write to the [program mailing list SITEROOT/ml.html] 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.


%!include: ../inc/footer.t2t
