		 _______________________________________
		|					|
		|	VEDIT PLUS Ver. 4.0		|
		|					|
		|	Converting 3.x macros to 	|
		|	the new 4.0 macro language 	|
		|_______________________________________|


This file is only of interest to users of VEDIT PLUS version 3.x. It
describes how to convert your existing VEDIT PLUS version 3.x command macros
to the new 4.0 macro language.


--------
Overview
--------

The new VEDIT PLUS 4.0 does not run command macros written for any previous
versions of VEDIT; the new macro language is completely different.

The supplied macro CONV3TO4.VDM will convert version 3.x macros to the new
macro language as closely as possible. CONV3TO4 can convert both:

*  .VDM command macro files.

*  .KEY files with keystroke macros that contain 3.x macro commands.

Every version 3.x command has an equivalent version 4.0 command and
CONV3TO4.VDM converts every command. However, because the new VEDIT PLUS has
a different organization for text registers and edit buffers, many converted
macros will not immediately work properly; you will manually have to correct
the way the macro uses registers and buffers.

The file NEW-40.TXT is a cross reference between all version 3.x commands
and the new 4.0 commands. It also includes all 3.x internal values and
configuration parameters. You will almost certainly want to print this file
if you perform any conversions.

Of course, the new VEDIT PLUS 4.0 has many additional commands, command
options and flow control statements not available in earlier versions. By
rewritting your macros to use these new features, many previously complex
or non-intuitive macros will become simpler and more understandable.


------------------
Using CONV3TO4.VDM
------------------

The first step in converting an existing 3.x macro is running the supplied
conversion macro CONV3TO4.VDM. You can run it from the DOS command line in
two ways:

	vedit -x conv3to4.vdm
OR
	vedit -x conv3to4.vdm macro.vdm -a macro.new
OR
	vedit -x conv3to4.vdm vedit.key -a vedit.new

		where:	'macro.vdm' is the old macro to be converted.
			'macro.new' is the new converted macro.

			'vedit.key' is a keyboard layout to be converted.
			'vedit.new' it the new converted keyboard layout.

The first way prompts you for the name of the file to convert. After entering
a filename, it requests confirmation to overwrite the existing file.
Alternatively, enter the filename in the form "macro.vdm -a macro.new"; this
specifies that the first file will be saved in the second filename.

If the first filename does not have a ".VDM" or ".KEY" extension, you are
prompted whether it is a keyboard layout file.

CONV3TO4 shows its progress by displaying each line of the macro as it
converts it. CONV3TO4 is not particularly fast, figure on 10 lines per second
on a 386 machine. CONV3TO4 is very accurate and carefully preserves all text
strings and comments. However, CONV3TO4 has several limitations:

*  It cannot convert very old style macros (e.g. version 2.x) that do not
   use "explicit delimiters". For example, it can convert F/text/ to
   Search("text"), but cannot convert the very old style "Ftext<Esc>".

*  If the original macro contains any syntax errors, such as missing
   delimiters or square-brackets, CONV3TO4 will get confused. It this case it
   will usually enter the command "Unknown:" and skip to the next line.

*  Macros that set up subroutines macros using "RI" will not have the
   subroutines macros converted. There is no way for CONV3TO4 to know that
   the text argument to "RI" is itself a macro. The best way to handle this
   is edit the original 3.x macro, comment out the "RI" command and its
   closing explicit delimiter, and then convert it with CONV3TO4. Finally,
   hand convert the original "RI" to the new "Reg_Set()" command. You may
   want to implement subroutines macros in a new and better way. See below.

*  There are incompatible difference between 3.x and 4.0 that CONV3TO4 cannot
   handle. You will have to search for and correct these by hand.

If CONV3TO4 encounters something it does not understand, it inserts the
command "Unknown" and skips to the next line. Several register/buffer
commands that cannot be converted unambiguously are followed with the command
"Warning:". Finally, obsolete configuration parameters are replaced with
"Obsolete".

Therefore, after running CONV3TO4 you should search for "Unknown", "Warning:"
and "Obsolete". You will have to hand convert these lines to resolve the
problem area.

Notes:

The 3.x "if" statement, without the else clause, will be converted to the new
"repeat()" command. This looks strange, but works correctly. For example,
consider the following 3.x "if" statement:

	(.bb=-1)[ .pXBB ]

CONV3TO4 will correctly convert it to:

	repeat (Block_Begin==-1) { Block_Begin(Cur_Pos) }

You will probably want to change it to the more understandable:

	if (Block_Begin==-1) { Block_Begin(Cur_Pos) }



-------------------------------------
Incompatibilities between 3.x and 4.0
-------------------------------------

Registers and Buffers are now independent
-----------------------------------------

Text registers and edit buffers are organized differently in version 4.0 than
they were in 3.x. VEDIT PLUS 3.x had 36 text registers, which could be
converted into edit buffers. In 4.0 the 100+ text registers are independent
of the 32+ edit buffers. Therefore, any 3.x macro that converted a text
register into an edit buffer will require some hand conversion.

It was common for a 3.x macro to copy a block of text into a register,
convert the register into a buffer, and then process the text in the buffer.
Consider the following 3.x macro code:

	.bb,.beRC(9)		R* Copy the block into T-Reg "9"
	EE(9)			R* Switch to buffer "9"
	B S/ //			R* Remove all spaces from the block

CONV3TO4 would convert this code to:

	Reg_Copy_Block(9,Block_Begin,Block_End)
	Buf_Switch(9)
	BOF() Replace(" ","")

However, this code will not work because buffer 9 will be empty after
switching to it.

When correcting this code, you should note that 4.0 has several "extra"
edit buffers (numbered 33, 34 and 35) that are reserved as temporary buffers
and are ideal for this type of code. These extra buffers cannot open files
and each macro (or keystroke macro) can freely use them.

The corrected code uses the temporary edit buffer #33:

	Reg_Copy_Block(9,Block_Begin,Block_End)
	Buf_Switch(33) Buf_Empty(OK)
	Reg_Ins(9)
	BOF() Replace(" ","")

If desired, the processed block could then be copied back to register 9 with
the command:

	BOF() Reg_Copy(9,ALL)


Registers and Buffers are now numbered
--------------------------------------

In 3.x the registers/buffers were named "0" - "9" and "A" - "Z". In 4.0
the registers are numbered "0" - "115" and the buffers are numbered "1" -
"36". Therefore problems can arise when converting from 3.x to 4.0.

To simplify the conversion of register names to numbers, 4.0 has an
"undocumented" feature - a register name in the range "A" - "Z" is
automatically converted to its upper-case ASCII value. Therefore the
following 4.0 commands are equivalent:

	Reg_Type(80)
	Reg_Type(p)
	Reg_Type(P)
	Reg_Type('P')

Therefore, register names convert without problems, because 4.0 will accept
the letter names. However, to remain compatible with future versions of
VEDIT PLUS, you should hand convert commands like "Reg_Type(p)" to
Reg_Type('P') or simply Reg_Type(80). Note that Reg_Type('p') is *not*
equivalent to Reg_Type('P'). Also, Reg_Type('0') is *not* equivalent to
Reg_Type(0).

However, since 4.0 only has 32 edit buffers and the ASCII values of "A" - "Z"
are "65" - "90", edit buffer names do not convert. You will have to convert
these commands by hand. The 3.x main buffer name "@" must be converted to
"1", "A" should be converted to "2", "B" to "3" and so on.

In summary, many 3.x "EE" commands, which are replaced with "Buf_Switch()"
will have to be hand converted to the correct code.


Commands are independent of configuration settings
--------------------------------------------------

The correct behavior of 3.x macros often depended upon setting various
configuration parameters. For example, "ES 8" controlled how search
errors were handled, while "ES 5" and "ES 6" set various search options.
In retrospect, this made macros difficult to understand and prone to
misbehave if all configuration settings, especially "ES" setting were not
correct.

As a big improvement, most 4.0 commands are independent of any configuration
settings. The behavior of commands is now modified with command options which
are specified on each command. For example, the "Search()" command has 15
possible options!

Many 3.x macros that depended upon non-default configuration settings, may
require some modification after running CONV3TO4. Here are the most common
examples:

*  3.x macros that needed "ES 8 2" should be modified to use the "NOERR"
   option on all applicable Search(), Replace() and Line() commands. Macros
   that needed "ES 8 1" must use the "ERRBREAK" option on these commands.

*  3.x macros that used "ES 6 1" to enable regular-expression searching
   must be modified to use the "REGEXP" option on all applicable Search(),
   Replace() and Match() commands.

*  3.x macros that used "ES 4 0" to leave the edit position at the beginning
   of an inserted block must be modified to use the "BEGIN" option on the
   applicable Reg_Ins() and Ins_File() commands.

*  3.x macros that used "ES 10 0" to perform local search and replace must be
   modified to use the "LOCAL" option on the applicable Search(), Replace()
   and Line() commands.

Notes:

To simplify "quick and dirty" conversions, the equivalent of "ES 8 2" can
still be selected with "Config(CM_SUP_ERR,2)". However, we HIGHLY recommend
against using it!  We will discontinue this feature in future versions.


Other Incompatibilities
-----------------------

*  3.x commands could use "\", "@" and almost any character as the text
   delimiters. These characters cannot be used as text delimiters with 4.0.
   Page 17 of the Macro Language Reference Manual lists the valid delimiters.

*  3.x commands that operated on blocks, such as ".bb,.beT" also moved the
   edit position to the beginning of the block. Although this was usually
   an undesirable side-effect, some macros depended upon it.  Since the 4.0
   block commands do not move the edit position, you will have to check for
   this.

*  Several pattern matching codes changed. You must correct these by hand:

   "|N" must be changed to "|!".

   "|X" must be changed to "|?".

   "|Rr" must be changed to "|@(r)", where 'r' is a text register number.



-------------------------
Optimizing macros for 4.0
-------------------------

VEDIT PLUS 4.0 has many new macro language features that can improve the
performance, structure and understandability of your macros. Here
are some suggestions:

*  Subroutines macros can now be placed in the current text register. For
   example, the 3.x command "M(r)" is converted by CONV3TO4 to "Call(r)". You
   may want to change it temporarily to Call("SUB-R"). Then add the label ":
   SUB-R:" to the end of the macro, place the subroutine code there and
   follow it with the "Return" command. Later you can give the subroutines
   better names.

   This prevents having so many text registers used by subroutine macros
   as in 3.x.  We also recommend the technique of placing all subroutine
   macros into register 101. Then use the command: Call(101,"SUB-R").

*  The flow control statements "while()", "do-while()" and "for()" give
   you more flexibility than just the old "repeat".

*  The commonly used 3.x command "0L" to move to the beginning of the
   current line can be replaced with the 4.0 command "Begin_Of_line()"
   or just "BOL()".

*  The commonly used 3.x command "N/|>/" to move to the end of the current
   line can be replaced with the 4.0 command "End_Of_line()" or just "EOL()".

*  The 3.x search commands ("F" and "N") always advanced the edit position
   past the matched text. For compatibility, CONV3TO4 always adds the
   "ADVANCE" option to the converted "Search()" command. Since the following
   commands often move the edit position back, you may want to optimize this
   code.

*  A converted Search() or Match() command is often followed by a test if the
   search/match succeeded.  This can be optimized by making the Search() or
   Match() the condition of the "if" statement.  For example:

	Search("text")
	if (Error_Match==0) {	// If search succeeded...
	    ...	
	}
	else {			// Else it failed ...
	    ...	
	}

   Can be optimized to:
	
	if (Search("text")) {	// If search succeeded...
	    ...	
	}
	else {			// Else it failed ...
	    ...	
	}

*  Examine how the supplied WILDFILE.VDM macro finds available (free)
   registers and buffers, uses them and then frees them again. A macro
   like this does not interfere with any other macros which are currently
   loaded or running.
