Just Another Macro Language v3.01

. . . . . . . . . . . . . . . . . . . . . . . . for HTML

Using j-SEX Modules

Table of Contents

• 1. General introduction
  
• 2. Installing a module
  
• 3. Using the extensions
  
• 4. Module defined user macros
  
• 5. Using more than one extension
  
• 6. Using different versions of modules
  

As these modules usually perform simple tasks we name these j-SEX Modules, (i.e.: Simple EXtension).

To use a j-SEX module you have to have access to the Perl source code of the module, and you have to install it. You need not be a Perl programming expert to use a j-SEX modules, however knowing Perl is not a drawback.

The release kit includes an example module, called example.pm. We will explain the usage of this module first, and then describe the methods more general.

jamal html preprocessor V{version}
Usage:

jamal [-options] input [output]

Options:
-? or -h               help
-m                     macro definition file
-D                     macro define
-I                     j-SEX directory
-0                     suppress output
-d                     put error message into result
.
Your default extension directories are:
D:\Perl\lib\i386-win32
D:\Perl\lib
.

In case you have no access to any of the directories that prints out on the machine that you use then you can specify an additional directory using the -I option of , example

               perl jamal.pl -I /etc/usr/users/meuser/myperlmodules test.jam

When you have copied the file to the location you can use the macros defined in it from any file. Note that the j-SEX module should be copied to the subdirectory named jamal below the /etc/usr/users/meuser/myperlmodules.

           {#use example}

This extension defines only two macros, called licence and list. This can be used to display a licence text on a Web page. A licence is usually printed all caps with initials printed using larger font. To write this in HTML requires lot of <FONT SIZE=+1> and alike typing.

The macro licence defined in the extension module example makes this job easy. It takes its argument as a text and convert all lower case characters to uppercase and all uppercase characters to <FONT SIZE=+1>x</FONT>, where x is the character itself. Therefore if you write:

        {#example::licence Here We Get All The Words Small Cap}

HERE WE GET ALL THE WORDS SMALL CAP

Because the macro use not only loads the extension module, but also sets it to be the base extension you can write

        {#::licence Here We Get All The Words Small Cap}

HERE WE GET ALL THE WORDS SMALL CAP

Note that the name of the macro in this case starts with the double colon. If you leave this will try to execute a built-in macro named licence and would eventually fail as there is no such built in macro. (By the way is freeware.)

The double colon is used to separate the module name from the macro name because Perl uses double colon for the same purpose.

There is a second optional argument to the macro use. This argument should be numeric if present and should define the version of the module that the file expects. compares this version number with the version installed, and if the installed version can not support the requested version i generates a fatal error.

See more information on version control in Writing j-SEX Modules.

When you use a macro defined by a module it should be preceeded by one of the character @ or # the same way as with built-in macros.

modulename::macro

The module example defines the user definable macro example::cap. As it is defined by the module it is equivalen to the definition:

      {#define example::cap/x=<FONT SIZE=+1>x</FONT>}

  {#define ExaText=This Is a Good Example}
  {#::licence {ExaText}}
  {#define example::cap/x=<FONT SIZE=+3 color=red>x</FONT>}
  {#::licence {ExaText}}

The redefinition of example::cap can also be written in the form

  {#define ::cap/x=<FONT SIZE=+3 color=red>x</FONT>}

To see what actual macros the different modules define and how altering tunes the behaviour look at the documentation of the specific extension module.

    {#use example}{#use pelda}
    {#example::licence Old Example}
    {#pelda::engedely Uj Pelda}

    {#use example}{#use pelda}
    {#example::licence Old Example}
    {#::engedely Uj Pelda}

Whenever you want to change the base extension you can use the macro with, which does not load any extension only sets the named extension to be the base extensions. Therefore the following example results again the same output as the examples above:

    {#use example}{#use pelda}{#with example}
    {#::licence Old Example}{#with pelda}
    {#::engedely Uj Pelda}

    {#use example}{#use pelda}{#with example}
    {#::licence Old Example}{#with}
    {#::engedely Uj Pelda}{#with}
    {#::licence New Example}

• example as the macro use not only loads the macro but also sets the base extension
• pelda as it is use-d, but remembers example being the previous base extension.
• example as it is set by the macro with, but remembers both pelda and example. Now we use this being a base extension calling the macro licence without specifying the extension.
• pelda as macro with takes the last remembered base extension, and example remains remembered.
• example as macro with takes this as the last remembered extension, and there remains no extension to be remembered.

    {#use example 1.0}

Specifying the version is a safe practice even if the version that macro file needs is the first version of the module. Later versions might change the behaviour and specifying the version we need gives them the chance to retard the behaviour to the specified version.