Possibilities - An SDL Primer - Part 2 - Building Menus

Contact:   eSoft, Inc. (Makers of TBBS)
           15200 E. Girard Ave., Suite 3000
           Aurora, CO  80014
           (303) 699-6565      Voice
           (303) 699-6872      Fax
           (303) 699-8222      BBS
           support@esoft.com   E-Mail

AN SDL PRIMER - PART 2 - BUILDING MENUS
---------------------------------------

*** From December 1990 Possibilities Newsletter ***
*** Copyright 1990 by eSoft, Inc.  All Rights Reserved ***

An SDL Primer -- Part 2: Building Menus
by Alan Bechtold

The TBBS System Definition Language Compiler (SDL), is easier than it looks.  
Simply put, it's just a different approach to designing and maintaining all 
of your TBBS system's menus.  Although you don't have to give up the 
comfortable menu-driven MEDIT program completely, you probably will -- after 
you start getting the drift of SDL -- because SDL is a complete replacement
for MEDIT in every way.

In our first installment in this series, we examined the SDL compiler and 
decompiler and actually put both to work.  Now, as promised, we're going to 
look closely at the language itself.

The TBBS System Definition Language is written using a variety of commands.  
These commands are written, usually one per line, in ASCII text files, 
called SDL source files.  SDL source files are written and modified using 
any word processor or text editor capable of creating and editing ASCII 
text.

Within any SDL source file, menus are defined in two basic parts: Macro 
Definition and Menu Definition.  We'll deal with Macros and how they work 
within your SDL source code in the next installment of this series.

Each menu definition in an SDL source code listing is begun with the "Menu:" 
Directive, followed by the name of the menu that's being defined.  A Menu 
Definition section is ended with the "EndMenu:" Directive.  Everything 
between the "Menu:" and "EndMenu:" Directives defines the menu named in the 
"Menu:" opening Directive.

Menu titles are written between the "Title:" Directive and the "EndTitle:" 
directive.  Each of these Directives is typed on a line by itself and 
everything typed on the lines between them will appear as the title of a 
TBBS menu on your system when the SDL source file is compiled.

Let's take another look at the sample menu we worked with in the last 
installment of this series:

Menu:1000
Billing:7
Title:
READ TBBS MESSAGES
------------------

EndTitle:
Entry:
<R>ead Messages
A1=--X-----
Key=R Type=6 Opt Data=Bulletin Board
...
EndMenu:

You should now be able to see that this menu definition will create a .CTL 
file named MENU1000.CTL.  The menu's title, as it will appear on the 
compiled TBBS system, will be "READ TBBS MESSAGES".  Another menu could be 
started, in the above SDL source listing, by typing "Menu:" and a different 
menu's name on a single line following the "EndMenu:" directive.

If you've done any work with MEDIT at all, it's fairly easy to see that SDL 
makes the simple task of writing out a menu's title even easier.  And it 
gets better.

The "Billing:" Directive follows the "Menu:" Directive in the above example.  
This assigns a TBBS Billing Class to the menu that's being defined.  If you 
don't specify a Billing Class in your menu, it will default to a Billing 
Class of 0.  For a complete discussion of TBBS Billing classes and how they 
work, see pages 2-14 through 2-16 in the TBBS manual.

Now you know how to start and stop, assign a billing class and create a 
title for each of your menus with SDL.  The next step is to set up each of 
your menu's options.  This is done with the "Entry:" block Directive.

The "Entry:" block is usually entered following the "EndTitle" Directive.  
Keywords following an "Entry:" Directive define each option that will be 
offered on the menu being defined.  In your SDL source file, you just write 
"Entry:" (without the quotes) on a line by itself to start an "Entry:" 
block.

In the sample menu above, there are five lines of text following the 
"Entry:" Directive.  These will set up one menu entry line that will be seen 
by a user with his or her A1 flag set to "--X-----".  It's a Type 6 menu 
option (Retrieve Messages) and will be activated when the user presses an 
"R."  In this case, the user will be presented with messages that have been 
posted on the BULLETIN BOARD message base, as specified in the "OPT 
DATA=Bulletin Board" statement.

Be sure to examine the sample menu above carefully as you read through the 
above paragraph.  Notice, for example, that only the A1 flags are defined.  
The above "Entry:" block could also have included definitions for the A2, A3 
and A4 flags.  They were omitted in the above example because only the A1 
flag was important to that menu option.  Any time you don't define a flag 
setting in the text following an "Entry:" Directive, SDL assumes those flags 
to be "--------".

Remember that each "Entry:" block is ended by the next Directive (which 
could be another "Entry:" Directive) or by the "EndMenu:" directive.

As I pointed out earlier, SDL works very much like MEDIT.  The main 
difference is that SDL lets you do everything in a text file, with your 
favorite word processor.  Believe it or not we've already covered everything 
you need to start writing SDL source files of your own.  One other Directive 
-- "Include:" -- will be discussed when we examine Advanced SDL issues, in 
an upcoming installment of this series.

Before we start writing SDL source code, however, we need to review some of 
the principals of the language's syntax.  Keep the following points in mind 
and your SDL source files will compile with the least number of errors 
possible:

STRUCTURE

As we've already discussed, SDL source files are basically broken into 
sections of two distinct types: Macro Definition and Menu Definition.  Each 
of these sections is delimited by a beginning and ending Directive.  Thus, 
each Macro Definition begins with "Macro:MacroName" and ends with 
"EndMacro."  Each Menu Definition begins with "Menu:MenuName" and ends with 
"EndMenu."

There is one exception to this rule.  When you start a new section of the 
same type as the previous one, you don't need to end each section with the 
"End:" Directive.  For example, when you're defining several menus within 
your SDL source file, you would start each menu with an appropriate 
"Menu:MenuName" Directive, but you only have to include an "EndMenu" 
directive on the last menu definition in the chain.  It goes something like 
this:

Menu:1000
     .
     .  Body of Menu 1000
     .
Menu:2000
     .
     .  Body of Menu 2000
     .
Menu:3000
     .
     .  Body of Menu 3000
     .
EndMenu:

DIRECTIVES

As we've discovered, these are the heart and soul of any SDL source file.  
When writing Directives into your SDL source file, remember that they must 
always begin with the first non-blank character of a line.  Directives also 
cannot contain any embedded blanks and they must always end with a colon.  
They can include an argument (such as a menu name on the "Menu:" Directive 
line, or the name of a macro on the "Macro:" Directive line), but anything 
past the argument (or past the Directive, if there is no argument) will be 
treated as a comment to the end of the line and will be ignored by SDL when 
compiling your source file into menus.

KEYWORDS

Keywords are used to specify arguments, which can be either Numeric, Flag 
settings or Text.  Keywords are always ended with an equal sign and are 
followed by the keyword's argument.  You can place keywords and arguments 
several to a line if you wish, or you may give each a line of its own.  
Arguments are always ended with one or more spaces or the end of a line.

In the sample source above, the keywords are "A1=" "Key=" "Type=" and "Opt 
Data=".  The text following each is that keyword's argument.  They could 
just as easily have been written out like this:

A1=--X----- Key=R Type=6
Opt Data=Bulletin Board

The one EXCEPTION to the above rules is "Opt Data=".  SDL will consider ALL 
the text that follows this keyword as a text parameter, to the end of the 
line.  This means that the "Opt Data=" keyword must be the last entry on a 
line.

UPPER AND LOWER CASE

Except for the text you enter between a "Title:" and "EndTitle:" Directive, 
upper and lower case are not considered unique by SDL.  You are perfectly 
free to use capitalization in your SDL code in any way that will make it 
easier for you to follow.

SPACES AND WHITE SPACE

You may indent your SDL source files any way you wish.  Whatever makes them 
easier for you to read.  The one exception to this is text between the 
"Title:" and "EndTitle:" Directives.  Any text appearing between these two 
Directives will display on your menu exactly as it was written in the source 
file.  Everywhere else, however, SDL considers any number of spaces as a 
single space, and will thus ignore the spacing you used when writing it.

CONTROL CHARACTERS

To indicate to SDL that you want a control character to become part of a 
menu when your source file is processed, it must be preceded by a "^" 
(without the quotes).  Thus, "control A" would be entered in your source 
code file as "^A" (without the quotes).  Of course, this means the "^" 
character is special in SDL.  If you wish to use it by itself, so it will 
display on a menu's title, for example, you must enter it twice ("^^") in 
your SDL source file.  This tells SDL "I really want a "^" to appear here -- 
NOT a control character."  A list of the 32 control characters and what they 
are appears on page 7-4 in your TBBS manual.

COMMENTS

It's always nice to add comments to your SDL source files, to remind you of 
why you did certain things, and to let other people who may have to use your 
SDL source files know what's going on.  Comments in SDL are simple:  just 
start a line with a semi-colon (;) and anything that follows it on the rest 
of the line will be ignored.  Needless to say, you can't enter comments 
inside of a "Title" or "Entry" text block or they will appear as part of 
your TBBS menu.

; This could be a comment in your SDL
; file. If you need more than one line
; just keep using semi-colons and text

Longer comments can be placed between a "Remark:" and its corresponding 
"EndRemark:" Directive.  This is indeed another SDL Directive, but its sole 
purpose is to allow you to include blocks of text within your SDL source 
files.  The "Remark:" Directive is used just like the "Title:" Directive.

Proper use of comments and "Remark:" blocks within your SDL source files 
allows you to actually include documentation for your source files within 
the source itself.  This can be a big help when you go back to modify your 
system later.

You now have all the tools you need to create an entire TBBS system with 
SDL.  Next issue, we'll look at adding POWER tools to your arsenal -- SDL's 
Macros and other advanced considerations.

Until then, your assignment is to add two more options to the sample menu 
above.  One should be "Write Messages" and the other should be "<G>oodbye -- 
Log Off System".  Make the "<W>rite Messages" option available to users with 
their A1 flags set to "--X-----" and the "<G>oodbye" option available to any 
caller.  Try compiling the menu (be sure to copy the source file and SDL.COM 
and SDLDC.COM into a subdirectory OTHER than your current working TBBS 
subdirectory).

- END -
PS1290-5
Rev. 12/90

Copyright (C) 1994 eSoft, Inc., All Rights Reserved.  Permission granted
to distribute this file in its entirety, without modification, to any
interested party.  Any other use requires the written permission of
eSoft, Inc.

IMPORTANT:  The information herein is subject to change without notice.
Please call or write to confirm factual information of importance to you
or your organization.

