_      _ _
                             /_\  __| (_)_ __  ___
                            / _ \/ _` | | '  \/ -_)
                           /_/ \_\__,_|_|_|_|_\___|

                           Allegro Dialogs Made Easy

                          Upgrading from Dime to Adime


                               by Sven Sandberg

What's This?

This file describes in detail everything you may need to do in order to upgrade a program written for Dime 1.2.4 or earlier, so that it uses Adime 2.0.0 or later.

The reason why I decided to prefix functions is that this is good coding practice: It avoids potential conflicts with other libraries that use the same identifier names. The reason why I had to change the name of the library from Dime to Adime is that there is another library called Dime (which is bigger and has been around longer) so it caused a conflict.

How to Upgrade a Program

First replace `#include <dime.h>' by `#include <adime.h>' in all your source files.

The most obvious difference now is that all identifiers are prefixed with `adime_'. You will get compiler errors, and the fix is usually obvious. But there are a couple of subtle differences that you may encounter:

"%bool[]": This now uses 0 for off and 1 for on. It used to be nonzero for on, but passing anything else than 0 or 1 is now an error.

"%filename[]" and "%string[]": These used to require a modifier specifying the maximum number of characters in the string. This has been changed: it now specifies the maximum number of bytes that these characters may occupy. These numbers are different in general because a Unicode character can occupy more than one byte.

`vdialogf()' and "%vdialogf[]": These now take an `adime_va_list' as parameter instead of a `va_list'. An `adime_va_list' is just like a `va_list', but is represented in a way that is more convenient for Adime. You can use `adime_va_start()', `adime_va_arg()', and `adime_va_end()' just like you use `va_start()', `va_arg()', and `va_end()', except for one difference: If you pass an `adime_va_list' to another function, and this function reads from it using `adime_va_arg()', then the position to read from will have advanced also in the calling function.

The internal way of defining a format has changed, so if you were doing this yourself you need to rewrite parts of the code. This is considered advanced though, so read internal.txt.

You may also want to uninstall Dime. You can do this by running "make uninstall" from Dime's (not Adime's!) directory. You can also do it manually by removing the files libdime.a and libdimed.a from your system's library directory, dime.h and dime/*.h from your system's include directory. Under djgpp you also need to remove djgpp/info/dime.inf or djgpp/info/dime.info.