Elec-c v3.02
____________

Copyright (C) 1987-1990 Bruce A. Mallett

All rights reserved






































Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1

Notice of warrantee . . . . . . . . . . . . . . . . . . . . . 2

Conditions of use . . . . . . . . . . . . . . . . . . . . . . 3

Contents of the Elec-c package . . . . . . . . . . . . . . . 4
Elec-c

Requirements . . . . . . . . . . . . . . . . . . . . . . . . 7

Installation . . . . . . . . . . . . . . . . . . . . . . . . 8

Feature overview . . . . . . . . . . . . . . . . . . . . . . 10

A quick "try-out" . . . . . . . . . . . . . . . . . . . . . . 12

Templates . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Template terminology . . . . . . . . . . . . . . . . . . 20
Rolling your own . . . . . . . . . . . . . . . . . . . . 20
Template Fields . . . . . . . . . . . . . . . . . . . . 21
Template commands . . . . . . . . . . . . . . . . . . . 24

Initializer files . . . . . . . . . . . . . . . . . . . . . . 31

Changing Elec-c parameters . . . . . . . . . . . . . . . . . 32
Elec-c

Reforming code . . . . . . . . . . . . . . . . . . . . . . . 35

Elec-c key bindings . . . . . . . . . . . . . . . . . . . . . 35
Elec-c

Files used by Elec-c . . . . . . . . . . . . . . . . . . . . 37
Elec-c

How Elec-c locates files . . . . . . . . . . . . . . . . . . 38
Elec-c



















Elec-c July 23, 1991
______________________
______________

-i-
i













Introduction
____________

Elec-c is a C language editor assist package for the Brief(tm)1
Elec-c
editor by Underware, Inc. Elec-c enhances Brief by adding
Elec-c
certain language specific capabilities which can greatly improve
your productivity. Among these enhancements are:

Comment assist. Elec-c will automatically position and line
Elec-c
up your comments in any column you designate.

Block comments. Elec-c blocks in your comments to create
Elec-c
headers and draw attention to important sections of code.

Templates. User definable templates for block comments
allow file and routine headers to be easily created.

Initial file processing. When a file is created Elec-c will
Elec-c
fill in the startup information for you!

Brace, bracket, and parenthesis checking. Elec-c can reduce
Elec-c
those common errors of leaving out a brace, bracket, or
parenthesis.

Brace alignment. When you type a closing brace Elec-c will
Elec-c
position it to the column corresponding to the opening
statement of the block.

Tag support. By keeping an up to date tag file Elec-c can
Elec-c
position you to any routine or include file within your
project with as little as two keystrokes!

Reformatting. A marked block of code may be reformatted to
your specifications.















____________________

1"Brief" is a trademark of "Underware, Inc.".
Brief


Elec-c July 23, 1991
______________________
______________

-1-
1
































Notice of warrantee
Notice of warrantee
___________________


I make no warrantee, either expressed or implied, of
I make no warrantee, either expressed or implied, of
the fitness of this package, in whole or in part, for
the fitness of this package, in whole or in part, for
any particular purpose. Any use to which you put this
any particular purpose. Any use to which you put this
package or any component of this package is done at
package or any component of this package is done at
your own risk. I will not be held liable for any
your own risk. I will not be held liable for any
damages which you may suffer as a result of its use or
damages which you may suffer as a result of its use or
misuse.
misuse.























July 23, 1991 Elec-c
___________________________________
_

-2-
2














Conditions of use
_________________

As the author of the Elec-c package I grant you, the user, a
Elec-c
license to use, modify, distribute, and make copies of this
package providing that:

- you do not sell this package or seek to make a profit by
the sale of this package or any modified version of it.

- this document and the copyright notices are retained
unmodified.

- you do not seek to restrict these rights from others.

Notes:

a) I did the work, I have elected to allow its use, I own
it, and I don't want someone trying to make money from it
unless I say they can. The amount of time I have
invested in this is non-trivial!

b) I have been releasing versions of Elec-c for several
Elec-c
years now and am aware that there are quite a number of
users. However there has been very little feedback and I
find it hard to believe that everyone is completely
satisfied with it. So in the future, if you use it, I
want to know it. If you are afraid of getting on a
mailing list or something then sign the postcard or
letter "anon". My interest is in getting comments and
some idea as to how many people use this package.





















Elec-c July 23, 1991
______________________
______________

-3-
3















Contents of the Elec-c package
Elec-c
______________________________

The Elec-c package comes in three archives, one called
Elec-c
Elec-c.zoo, which contains all of the macros and data files to
__________
run the basic package with Brief, one called indent.zoo which
__________
contains a C source code reformatter, and one called Tags.zoo
________
which contains the source and executable for the tags program.
The contents of these archives follows:

Elec-c.zoo
__________

ASCFIND.CB The Brief macros that implement the
file-search strategy used by Elec-c.
Elec-c

BAM.M This is a copy of my initials macro,
constructed by Brief's "Setup"
utility and modified to support
Elec-c.
Elec-c

BRIEF.INI Contains configuration information
for Elec-c.
Elec-c

CONFIG.CB A Brief macro file. Inquires and sets
configuration information from/to
"BRIEF.INI".

EC-BOX.CB A Brief macro file. This is the
portion of Elec-c which deals with
Elec-c
box comments.

EC-SET.CB A Brief macro file. This is the part
of Elec-c which deals with the
Elec-c
presentation and setting of Elec-c
Elec-c
parameters.

EC-TAGS.CB A Brief macro file. This is the
portion of Elec-c which implements
Elec-c
the tags facility.

EC-TOP.CB A Brief macro file. These are the
top-level macros which run the Elec-c
Elec-c
package.

EC-TPLAT.CB A Brief macro file. This contains
the Elec-c routines which deal with
Elec-c
templates and which are separably
loadable.



July 23, 1991 Elec-c
___________________________________
_

-4-
4















ELEC-C.DLG This contains the dialogue box
definition used by Elec-c to set its
Elec-c
parameters in response to an EcSet
command (ALT-F2).

ELEC-C.DOC This file.

ELEC-C.H A Brief include file. This contains
Elec-c definitions.
Elec-c

ELEC-C.CB A Brief macro file. These are the
macros initially loaded when Elec-c
Elec-c
is started and they comprise the
minimal set of macros necessary to be
compatible with Underware's
language.cb package.

INITIAL.CI A sample initial file for
initializing new .C files.

INITIAL.HI A sample initial file for
initializing new .H files.

README Last minute notes, alerts, and
whatever (if present).

TEMPLATE.C Sample template definitions.


Indent.zoo
__________

ARGS.C The source code
CODES.H
COMMENT.C
CONFIG.H
GLOBS.H
INDENT.C
IO.C
LEXI.C
MSDOS.H
PARSE.C
TYPEDEFS.H

CHANGES.DOC Describes the damage that I did to
the original source code.





Elec-c July 23, 1991
______________________
______________

-5-
5














INDENT.1 The original nroff version of the
unix man page.

INDENT.MAN The formatted version of the manual
page.

INDENT.EXE The executable.


Tags.zoo
________

ATOM.C C source for the atomizer

ATOM.H Include file for atomizer specific
definitions

CONFIG.H My standard configuration data.
Alter as suits your machine.

DEFINES.H Definitions applicable to the entire
"Tags" project.

DIR.H Include file substitute for the unix
equivalent.

EXTERNS.C All of the externals used by the
project.

EXTERNS.H Definitions of everything in
EXTERNS.C

FMATCH.C File matching code for scandir().

INIT.C Code to initialize the Tags package.

LICENSE.TXT License agreement.

MAIN.C The main() routine for the Tags
package.

MAKEFILE Make file (for NDMAKE).

PROCESS.C Code to process file specifications.

PROJECT.H Central include file for the Tags
project. All routines in the project
must include this.




July 23, 1991 Elec-c
___________________________________
_

-6-
6














README Last minute updates, alerts, and
whatever (if present).

RTNDEFS.H Routine prototypes. This is
regenerated by the makefile (if you
delete it) for MSC environment.
(note that there will be errors
during the regeneration, these are
ok).

SCANDIR.C Implements a close approximation of
the BSD scandir() package.

SWITCHES.C Switch specific routines.

SWITCHES.H Switch specific definitions.

TAG.C Code to do the actual tagging.

TAGS.DOC Documentation for the Tags program.

TAGS.EXE The executable.

TYPEDEFS.H Type definitions which I use to help
make things more portable.

USAGE.C Implements a terse help display for
Tags.

Note:
The DIR.H, FMATCH.C, and SCANDIR.C files are slightly
modified versions of some which I found in the public
domain. I am grateful to whoever wrote these and
apologize for loosing track of from whence they came
(if ever I knew)!


Requirements
____________

I apologize for the uncertainty evident in this section, a result
of limited means to test Elec-c on various configurations. It is
Elec-c
my hope that users will report to me the configuration on which
they are running Elec-c so that I may include more information
Elec-c
here. In the meantime let me tell you what I have ...

I developed this version of Elec-c using Brief version 2.1.
Elec-c
While I have not tested it, it may run on an earlier 2.x release.
It definitely will not run on a pre-2.0 release. As new versions
____



Elec-c July 23, 1991
______________________
______________

-7-
7














of Brief are introduced (and as I am able to keep pace with them)
I will attempt to update Elec-c to take advantage of newer
Elec-c
features. Thus at any point (and without warning) you may find
that a new download of Elec-c will not work with a particular
Elec-c
older version of Brief. Sorry.

I have used this release on two AT-class and various 386
machines. There is nothing inherent in Elec-c to prevent its
Elec-c
being run on an XT, but since it is very CPU intensive I would
not recommend it unless you are given to frequent bouts of
hibernation ...

This version of Elec-c has been run under MSDos 3.2, 3.3, 4.01,
Elec-c
and 5.0 on machines with 640k of memory and a hard disk. I do
not know what the earliest version of Dos it will run on (I
suspect 2.0), this is more a function of Brief then of Elec-c.
Elec-c
Nor do I know what the minimum memory requirements are.

There, now do you feel better informed?


Installation
____________

The installation of Elec-c is straight-forward. I would
Elec-c
recommend the following approach:

- use a de-archiver extract the Elec-c archives in a
Elec-c
separate directory. For example if you downloaded a .zip
file containing elec-c then:
pkunzip elec-c
pkunzip indent
pkunzip tags

- compile all of the ".cb" files using the "cb" compiler
distributed with Brief. For this you may want to enter
the following command at the DOS prompt:
FOR %F IN (*.cb) DO cb %f
If you are using 4DOS you may need an extra percent
(depending on what version of 4DOS you are using):
FOR %%F IN (*.cb) DO cb %%f

- move the following files to your brief macros directory
(usually \brief\macros):
*.cm (the compiled files)
brief.ini (configuration data)
elec-c.dlg (Elec-c dialogue/parameters data)
Elec-c
template.c (sample box comment templates)
copyrite (you will want to edit this)



July 23, 1991 Elec-c
___________________________________
_

-8-
8















- move all of the .exe and .com files to a directory in your
search path (perhaps \util or \bin)

- add "-melec-c" to your BFLAGS environment variable. For
most this will require that you edit AUTOEXEC.BAT and
locate the line containing "SET BFLAGS=...". To this you
need to add the "-melec-c" switch to startup Elec-c. My
Elec-c
AUTOEXEC.BAT now contains the following line:
SET BFLAGS=-i60l255pu100z -mBAM -mrestore -melec-c
-Dega

- edit your BPACKAGES environment variable to designate the
file type you want Elec-c to be invoked with. This is
Elec-c
done in the same manner as you would designate Underware's
"smart" or "template" editing packages except you use "ec"
to designate Elec-c. My AUTOEXEC.BAT contains the
Elec-c
following line to setup BPACKAGES:
SET BPACKAGES=rc,h,c,cpp,cb-c:s 0 0 0,ec;m:s 0 0
0,t

This BPACKAGES designates that Underware's "smart.cb" and
Elec-c are both to be invoked when any file having an
Elec-c
extension of "rc", "h", "c", "cpp", or "cb" is edited.

Note: Elec-c is compatible with both of
Elec-c
Underware's "template.cb" and
"smart.cb" packages. However using
"template.cb" will limit Elec-c's
Elec-c
functionality since "template"
editing generates matching
parenthasis and braces for you.
This circumvents Elec-c's ability
Elec-c
to check for mismatched
parenthasis, braces, and brackets
which it can only do if you type
___
the closing character.

- That's it!












Elec-c July 23, 1991
______________________
______________

-9-
9














Feature overview
________________

This is just a terse section for those of you who know what you
are doing (or think you do) and want to see what Elec-c does. So
Elec-c
here goes.

/* Whenever you begin a comment Elec-c
/* Elec-c
provides one space and watches to see
what the next character is. If it is

another asterisk then you are placed in
a "box comment" buffer and allowed to
enter a comment. Strike "*/" to exit.
*/

If it is an asterisk then what Elec-c
Elec-c
does next depends on what is to the left
of the cursor. If there is only white
space (tabs, spaces) then continue
typing in your comment. Elec-c will
Elec-c
word wrap for you and supply leading
asterisks beneath the opening one until
you close the comment by typing "*/".
*/

If there is a non-white space character
to the left of the cursor then the
comment will be repositioned to the
comment column. Elec-c will word wrap
Elec-c
for you as you continue to type and
align the comment complete with leading
asterisks below the opening sequence.
Close the comment as you would normally
by typing "*/"
*/

/* If typed when the cursor is positioned
/*
between the opening "/*" and the closing
"*/" of a box comment this will open the
box comment for editing. Use this to
make changes to existing box comments.

ALT-T When you are in the box comment buffer
ALT-T
this command will call in a designated
template. You will be prompted for the
name of the template. Hit to
abort. Note that this key only works
when you are in the box comment buffer.

ALT-G The normal goto-line function now serves
ALT-G
several purposes: it allows you to go to
a particular C tag, to an include file,



July 23, 1991 Elec-c
___________________________________
_

-10-
10














and to a particular line. When struck
it prompts for the line number (as is
normal) at which point you can supply
either a line number, the name of an
include file (preceeded by either "<" or
"#"), or a tag name. The word under the
cursor will appear as the default
answer, to accept it just strike return.
If the cursor is on a #include line the
name of the include file will appear as
the default. Typing in a number will
invoke the normal goto_line function,
any other input will attempt to locate
either an include file or a tag by that
name and position the cursor on it. A
dialogue box will be presented to
resolve ambiguous tag specifications.
Note that this key binding becomes the
normal goto_line when you are in the box
comment buffer.

Double Click Double clicking the mouse on a word in
Double Click
the source file or on a #include line
has the same effect as if you had struck
ALT-G, only without the prompting. This
is a faster method of going to a tag or
include file.

ALT-F2 This will present a dialogue box
ALT-F2
containing the Elec-c parameters and
Elec-c
allow you to change them.

TAB A marked block may be indented one tab
TAB
stop for each press of the tab key.
Note that column marking also works and
indents only those columns to the right
of the marked area.

SHIFT-TAB Like TAB but outdents.
SHIFT-TAB TAB

{ When typed in column 1 this key assumes
{
that you are defining a new function.
It will supply the closing brace and a
comment which names the function being
closed. Sorry, but at the moment this
only supports my C coding style.





Elec-c July 23, 1991
______________________
______________

-11-
11














) Shows you the matching opening
)
parenthesis if it is on the screen.
Tries to be intelligent about
intervening strings, comments, and
continuation lines.

] Like ")" but for brackets.
] )

} Shows you the matching opening brace (if
}
it is on the screen) and checks
everything between for proper matchups
of parentheses, brackets, and braces.
Places the closing brace in the same
column as the first non-blank character
of the line containing the corresponding
opening brace.

SHIFT-LEFT-ARROW Within box comments moves you to the
SHIFT-LEFT-ARROW
previous template field.

SHIFT-RIGHT-ARROW Within box comments moves you to the
SHIFT-RIGHT-ARROW
next template field.

F10-ReformBlock Uses the indent utility to reformat the
F10-ReformBlock ______
marked block of text.


A quick "try-out"
_________________

This section is for those anxious to get to work using Elec-c and
Elec-c
to see just what it can do! Here I will quickly run you through
a few of the Elec-c features by asking you to type in a short
Elec-c
program that exercises its most commonly used functionality. For
many this may be all that you will need to read, however if you
really want to get the full power of this package I encourage you
to read this entire document and to experiment.

The program that we are going to create is commonly used in C
programming examples: "printenv.c" will print out the environment
__________
strings when no arguments are given it or will print out only
those which match its arguments. Lets begin at the Dos prompt in
some directory in which you don't mind creating a scratch file or
two (and in which "printenv.c" does not already exist) and create
__________
the file:

C>b printenv.c
b printenv.c





July 23, 1991 Elec-c
___________________________________
_

-12-
12














Brief will come up and display its version number in the command
area. You should also see something new: the Elec-c sign-on
Elec-c
banner and my copyright notice! After a short delay the
copyright notice disappears and a "beep" will sound to draw your
attention to the following message at the bottom of the screen:

Initialize file (y,n) ?
Initialize file (y,n) ?

Because you are opening a new file Elec-c is asking if you want
Elec-c
the file initialized to a predefined format. This is covered
later in the documentation, for now answer no by typing "n".
_
That done, you should be looking at an empty screen just begging
for something a bit more exciting to display!

On the next page is the listing of the program, type it in just
as you see it, don't worry about the formatting, Elec-c will
Elec-c
handle this for you!2























____________________

2There are a number of different styles used by C
programmers, their adherence to and fanaticism for a particular
one often borders on the religious. This implementation of
Elec-c allows it to support a number of the more common styles.
If you have one that you prefer, please try it out. If you do
not, then I urge you to follow the example as it is. Eventually
you will find yourself becoming comfortable with a particular
style.


Elec-c July 23, 1991
______________________
______________

-13-
13





















#include
#include
#include
#include

1 main( argc, argv, envp )
1 main( argc, argv, envp )
2 int argc;/*Number of arguments*/
2 int argc;/*Number of arguments*/
char ** argv;/*Argument Vector*/
char ** argv;/*Argument Vector*/
char ** envp;/*Environment vector Pointer*/
char ** envp;/*Environment vector Pointer*/

3 {
3 {
int i; /*HDV (Handy-Dandy-Variable)*/
int i; /*HDV (Handy-Dandy-Variable)*/
int len; /*Length of argument being
int len; /*Length of argument being
examined*/
examined*/
4 unsigned char print_it; /*Whether this variable is
4 unsigned char print_it; /*Whether this variable is
printed or not*/
printed or not*/

print_it = 0; /*Init. this*/
print_it = 0; /*Init. this*/

if ( argc < 2 )
if ( argc < 2 )
print_it = 0x2;/*Always print*/
print_it = 0x2;/*Always print*/

for ( ; (envp)[0]; ++envp )
for ( ; (envp)[0]; ++envp )
{
{
print_it &= ~0x1;/*Clear low order bit*/
print_it &= ~0x1;/*Clear low order bit*/

for ( i=1; i for ( i=1; i {
{
len = strlen(argv[i]);/*Get length of this
len = strlen(argv[i]);/*Get length of this
argument*/
argument*/

if ( (strnicmp(argv[i],envp[0],len) == 0) &&
if ( (strnicmp(argv[i],envp[0],len) == 0) &&
(envp[0][len] == '=' ) )
(envp[0][len] == '=' ) )
{
{
print_it |= 0x1;/*Enable printing*/
print_it |= 0x1;/*Enable printing*/
break;/*Go for it*/
break;/*Go for it*/

Figure 1 - Printenv.c sample program
1 __________








July 23, 1991 Elec-c
___________________________________
_

-14-
14














Notes
_____
1) When you typed the closing parenthesis ")" Elec-c
Elec-c
showed you where the matching open parenthesis is
located. When it searched for the match it also
checked to make sure that all brackets ("[" & "]")
were properly lined up and that there were no braces
("{" & "}"). Should you make a mistake and leave a
set unmatched then Elec-c will warn you.
Elec-c

2) If you typed in the program just as it is shown
above (i.e., you did not attempt to "neaten it up")
then you will have noticed that Elec-c moved your
Elec-c
comment into position as it was being typed in.

3) When you type an opening brace ("{") in column 1
Elec-c supplies a closing brace complete with a
Elec-c
comment showing the name of the function which it is
closing.

4) This comment is deliberately long. As you type
Elec-c will automatically word wrap it and supply an
Elec-c
asterisk or two to make it look nice.

5) You do not need to position the closing brace,
Elec-c will put it in the same column as the first
Elec-c
non-white space character of the line containing the
matching opening brace!

At this point you should be able to compile and run the program.
While adequate for short, uncomplicated programs, this one is not
as well commented as it could be. The loop, for example, should
have a header comment which explains what it does. So add one
now by positioning the cursor on the blank line above the "for"
statement in column 5 (right above the "f" in "for"). Type the a
slash (division sign) and two asterisks, as follows:
/* (note that the cursor moves over one space.. Elec-c is
/* Elec-c
_______________________________________________________
watching to see what you type next!)
____________________________________
* (the screen clears!)
* ____________________

Typing "/**" is a special signal to Elec-c: it indicates that you
Elec-c
desire to create a "box comment". Box comments are ... well,
box comment
____________
never mind, you will see soon enough. Type in the following text
(you do not need to break each line, Elec-c will perform the word
Elec-c
wrapping as you type):
The following loop will examine each environment
The following loop will examine each environment
variable passed via the "envp" vector. Each is checked
variable passed via the "envp" vector. Each is checked
in turn against all of the arguments to the program. A
in turn against all of the arguments to the program. A




Elec-c July 23, 1991
______________________
______________

-15-
15














match will set the low order bit of the "print_it"
match will set the low order bit of the "print_it"
flag.
flag.

There, that explains the loop a bit better. End the box-comment
just as you would end any other comment, type:
*/
*/

Now you know what a box comment is! Elec-c has surrounded your
Elec-c
comment with asterisks and corner angles to call attention to
this comment. But what if you want to edit it again? Lets do
so:

Move the cursor somewhere inside the box comment. Note that by
______
"inside" I do not mean that it must be inside the box, only that
it must be between the "/*" which opens the comment and the "*/"
which closes it (i.e., it is "inside" the comment). Now type the
following:
/*
/*

Voila! Elec-c sees that you are starting a comment. Doing so
Elec-c
inside a comment makes no sense, however, and since you are
within a box-comment Elec-c assumes that you desire to edit it.
Elec-c
Move to the end of the last line and add the following:
Note that the string comparison function used is
Note that the string comparison function used is
"strnicmp" which treats upper and lower the same.*/
"strnicmp" which treats upper and lower the same.*/

As before, the "*/" ends the comment.

Elec-c will position the box comment so that its left edge is in
Elec-c
whatever column the cursor was in when you created it. This box
comment is aligned with the "f" in "for" because that is where
the cursor was when we started. Some programers would prefer to
have this comment starting in column 1. If you are one, or even
if you are not, try this:
-move the cursor to column 1 of the first line of the box
comment (the line containing the "/*")
-type Alt-A to set an anchor.
-define a block containing the box-comment by moving the
cursor down to column one of the line following the "*/"

Elec-c allows you to move a block of text in or out by a tab
Elec-c
stop. To see this press the "tab" key. Each time you press it
the marked block will move in one tab stop. To move it out press
"shift-tab". Do this until you get the block with its left edge
at column 1, then unmark the block (press Alt-A again). You
could leave the box comment like this, but the right edge will no
longer match other box comments. To fix this simply enter the
box comment and then immediately exit it:



July 23, 1991 Elec-c
___________________________________
_

-16-
16














-position the cursor with the box comment.
-type "/*" to open the box comment
/*
-type "*/" to exit the box comment
*/

Note: Elec-c will not reformat the contents of an existing box
Elec-c
___________________________________________________________
comment, hence the word boundaries remain the same. This
___________________________________________________________
can cause a problem if you enter a box comment that you
___________________________________________________________
have tabbed to the right and you exit it before
___________________________________________________________
reformatting it. In this case anything beyond the word
___________________________________________________________
wrap column will be truncated by Elec-c in order to fit
Elec-c
___________________________________________________________
the box.
________


Since I have gotten you involved in box comments, let me show you
one other feature of Elec-c: templates. If you have installed
Elec-c _________
the package correctly you will have copied a file called
"template.c" to your Brief macros directory (as designated by the
"BPATH" environment variable). This file contains a number of
templates which can be called up from within a box comment. I
have defined two, one for adding file headers and one for adding
routine headers. Prior to using these please exit Brief and
define the environment variable "USER" with your user name. If I
were doing this then I would go to the DOS prompt and type the
following:

C>set USER=Bruce A. Mallett
set USER=Bruce A. Mallett

Now edit the file again:

C>b printenv.c
b printenv.c

Press HOME three times to get to the beginning of the file, press
HOME
carriage return to open a blank line, and up arrow once to get
back to the beginning of the blank line. Now open a box comment:
/**
/**

You should be in the box comment buffer looking at a blank
screen. Press ALT-T. You will be prompted for a template name.
Elec-c supports user defined templates which can be
Elec-c
_______________________________________________________
called up only within box comments. A template can be
_______________________________________________________
as simple as just a stream of text to be inserted into
_______________________________________________________
the box comment buffer, or it can consist of text and
_______________________________________________________
macros which are executed to customize the box comment.
_______________________________________________________
All templates are named, the ones in the distribution
_______________________________________________________
("template.c") have simple one character names (I don't
_______________________________________________________
like to type a lot).
____________________





Elec-c July 23, 1991
______________________
______________

-17-
17














Since we are about to add a file header we will use the "f"
template (that's a hint: answer "f"). Note what has happened!
_
Elec-c created a file header containing the name of the template
Elec-c
(so that Elec-c can figure out what it is if you open the box
Elec-c
comment up again later), the name of the file, your name (which

is why you set the "USER" environment variable), today's date,
and the contents of the file "COPYRITE" (which, if you still have
mine from the distribution kit means that you have added my
copyright to your program. Send me your computer and I will not
press charges). Elec-c will also position you to a "Description"
Elec-c
field so that you can fill it in. Type the following:
This file contains a program to print out all the
This file contains a program to print out all the
environment variables (no command line arguments) or
environment variables (no command line arguments) or
the environment variables matching those given as
the environment variables matching those given as
arguments.*/
arguments.*/

Now try the other template (called "r"). Move to the beginning
of a blank line just above "main(...)" (create a blank line and
position the cursor to the beginning of it if there is not
already one there). Open up a box comment, type ALT-T and call
ALT-T
in the "r" (for routine) template. This is the template that I
_
use at the beginning of every routine in my C programs. I am not
going to guide you through filling it out, my purpose in having
you call it up is to show you template "fields". Fields are
______
simply ways of positioning the cursor to predesignated points
within a template. Each time you press "Control-DownArrow"
Elec-c will move you to the next field (wrapping to the first).
Elec-c
In like manner pressing "Control-UpArrow" will take you to the
previous field (wrapping to the last).

This quick-start should be enough to get you off and tinkering on
your own. I encourage you to come back and read the rest of this
document when you get a chance as I am sure that you will find
the other features equally beneficial.


Templates
_________

I think that you will agree that one of the nicer features of
Elec-c is its ability to create box comments. Box comments give
Elec-c
your programs a polished, professional look, they allow you to
call attention to important sections of code, and they are ideal
for headers to files, modules, and loops.

As headers, however, they frequently require the same contents
with slight variations according to what they "head". For
example a company project at "Trendy Software, Inc." would
probably want every file to have a header containing the name of



July 23, 1991 Elec-c
___________________________________
_

-18-
18














the file, the date it was created, the name of the author, and
Trendy Software's copyright notice. The header might look like
this:

File: USAGE.C

Author: Ralph Jettson

Date: May 19, 2003

Notice: Copyright (C) 2003 Trendy Software, Inc.
All rights reserved.

The above example shows a form containing fixed data (various
field titles such as "File", "Author", and "Date", and the
copyright notice) and variable data (the file name, the name of
the author, and the date). Elec-c has a facility called
Elec-c
Templates which allow you to create forms containing just this
_________
sort of mundane, repetitive data.

Elec-c templates are programable. This lets you create your own
Elec-c
file and routine headers, specify the initial contents of a .c or
.h file, design comments that let you track software revisions,
and just about anything else you can think of to do with
programmable box comments!

Elec-c uses a template file named in the configuration file.
Elec-c
When the user requests a template Elec-c will search for this
Elec-c
file (the default name is "template.c") first in the current
directory, then in the directory above that, and so on until it
is found or until the root directory has been searched. If it
has still not been located then the BPATH is searched.

Once found Elec-c extracts the named template from the template
Elec-c
file and inserts its text in the current buffer. It processes
the buffer by executing commands contained there-in. These
commands form a lisp-like language similar to that used to
program Brief.













Elec-c July 23, 1991
______________________
______________

-19-
19














Template terminology
____________________

There are only a few terms that I use to describe templates,
these are presented below:

field A field is a particular text item within the
_____
template that Elec-c remembers. Fields are
Elec-c
typically used to position the cursor. A field is
designated by the FIELD macro.
FIELD

fixup When a template is called in to a box comment
_____
(either directly by the user asking for it or by
an initialization file) Elec-c will process the
Elec-c
template prior to putting it into the box comment
buffer. During the processing all template macros
are extracted and executed and designated fields
are set aside in a special buffer so that Elec-c
Elec-c
can remember them should they be referenced while
the box comment is being edited. This processing
stage is called the template fixup.
fixup
_____

macro A macro is a special command to Elec-c that
Elec-c
_____
appears within the template definition. Normally
all text within a template is inserted into the
box comment buffer just as it is. However during
the fixup stage Elec-c will treat any text between
Elec-c
".(" and ")." as a macro, executing innermost
macros first. Template macros are individually
detailed in a following section.


Rolling your own
________________

All templates are defined in a file called "template.c" which
must be somewhere in the Elec-c search path (see How Elec-c
Elec-c __________
locates files). This file may contain any number of template
_____________
definitions. Each definition begins with a line that contains
the template name (any number of alphanumeric characters)
bracketed by "<^" and "^>3. The definition ends with a line
containing only "><" (no other spaces, nut'n else anywhere on the
____
line).




____________________

3Elec-c will insert the entire contents of this line at the
Elec-c
___________________________________________________________
beginning of the box comment so that it may later identify the
_________________________________________________________________
template should you reopen it.
______________________________


July 23, 1991 Elec-c
___________________________________
_

-20-
20














When a template is requested Elec-c will search the template file
Elec-c
for the named template bracketed as described above. This line
and all following lines up to (but not including) the terminating
line are copied into the box comment buffer. The template is
then "fixed-up".

Fixup processing involves looking for matching pairs of ".(" and
").", everything between is assumed to be a macro. The macro is
deleted from the buffer and then executed (see the individual
macro definitions below to determine what they do). Any text
inserted as a result of the macro being executed replaces the
macro in the box comment.4 Likewise any text deleted by the
macro disappears from the box comment buffer. Macros may be
nested, the innermost macros are executed first as expected.


Template Fields
_______________

Fields may be defined within a template too aid in the
positioning of the cursor. A field is simply a string that
Elec-c searches for (when requested) followed by optional cursor
Elec-c
positioning information. When a box comment is opened Elec-c
Elec-c
determines the template in use (from the header), locates the
definition in template.c, and extracts the corresponding field
definitions. The "_NextField" and "_PrevField" macros (by
__________ __________
default bound to shift-down-arrow and shift-up-arrow,
respectively) use these field definitions to position the cursor
as follows:

- A search for the field name is made and the cursor
is positioned immediately following the name.

- If the field was defined with a line-move parameter
(see the FIELD definition) then the cursor is moved
_____
(plus or minus) that many lines.

- If the field definition included a column-position
parameter then the cursor is moved to that column.

Elec-c will always store the template name as the first line in a
Elec-c
template. This allows it to identify the template should the box


____________________

4For those Brief programmers among you Elec-c is actually
Elec-c
___________________________________________________________
passing the entire string discovered between the ".(" and the
_________________________________________________________________
")." to Brief's execute_macro function. This means that you are
execute_macro
_________________________________________________________________
not limited to the template macros which I have supplied, instead
_________________________________________________________________
you can supply any macro that you like!
_______________________________________


Elec-c July 23, 1991
______________________
______________

-21-
21














comment be reopened and thereby to gather the field definitions
from the template.c file. Be careful to note that Elec-c
Elec-c
requires every template to have at least one FIELD definition.
FIELD
_______________________________________________________
This is so that Elec-c can determine where the cursor is to
Elec-c
initially be placed. Even if your template has no need for them
be sure to define one dummy field.

An example
__________

The template.c file which I distribute in the Elec-c package
Elec-c
defines two of the templates which I use the most. One, called
simply "f" (for file), I place as a header at the top of every .c
f _
and .h file. Allow me to start with a "requirements spec." for
this template:

1) the template must identify the name of the file
(including extension).
2) the file name must be in lower case.
3) the name of the file's creator and the creation date
must be included.
4) an applicable copyright notice must be included.
5) there must be an area in which the programmer can
type in a description of the file.

Now to start building the template. First, the template name
must be taken care of, I have already chosen this to be "f". So
I start with the following:

<^f^>
<^f^>
o o o o o The template definition will go in here!
_________________________________________
><
><

Requirement 1 is easy: the file name and extension are available
through the use of the FNAME and FEXT macros. So ...
FNAME FEXT

<^f^>
.(FNAME)...(FEXT).
.(FNAME)...(FEXT).
><

There are three periods in a row, two because the macro
invocations require them and one to be inserted between
the file's name and extension components.

Requirement 2 is also easy since a template macro exists to
convert a string to lower case. Therefore ...

<^f^>
.(LOWER .(FNAME)...(FEXT).).
.(LOWER ).



July 23, 1991 Elec-c
___________________________________
_

-22-
22














><

Since template fixup involves processing the inner-most
macros first the file name and extension get inserted
in place as a parameter to "LOWER", which then converts
the entire thing to lower case.

Requirement 3 says that the name of the file's creator and the
creation date is to be inserted. The date is easy, since a
template macro also exists to do this. But Elec-c has no idea of
Elec-c
the name of the person at the keyboard! So I have established
the convention that my AUTOEXEC.BAT file define a environment
variable called "USER" to supply my name. Hence ...

<^f^>
.(LOWER .(FNAME)...(FEXT).).
.(ENV "USER"). .(DATE).
.(ENV "USER"). .(DATE).
><

Requirement 4 calls for the inclusion of "an applicable copyright
_______________________
notice". For me what is "applicable" varies depending on whose
______
project I am working on. When doing my stuff it is copyright by
Bruce A. Mallett, when working under contract it must contain the
proper client name. It seems that the best solution is to put
the notice in a separate file and thereby make it external to the
template definition. This notice can then be located as required
and pulled in by Elec-c. Now the template definition looks like
Elec-c
this ...

<^f^>
.(LOWER .(FNAME)...(FEXT).).
.(ENV "USER"). .(DATE).
.(FINSERT "COPYRITE").
.(FINSERT "COPYRITE").
><

During fixup processing Elec-c will locate the file
Elec-c
called "COPYRITE." (no extension) and insert its
contents at the appropriate position in the box comment
buffer. Note that the file lookup uses "_AscFind" (see
How Elec-c locates files) making it ideal for project-
Elec-c
________________________
oriented C programming.


Requirement 5 asks for an area in which to let the operator
insert a description of the file. This is a good use for FIELD
since we will want to position the cursor to the area when the
template is initialized or the box comment reopened and since all




Elec-c July 23, 1991
______________________
______________

-23-
23














templates require at least one FIELD. And so the definition
evolves ...

<^f^>
.(LOWER .(FNAME)...(FEXT).).
.(ENV "USER"). .(DATE).
.(FINSERT "COPYRITE").
.(FIELD "Description:" 0 15).
.(FIELD "Description:" 0 15).
><

The parameters "Description:", "0", and "15" position
the cursor. After "Description" is located in the box
comment the cursor is moved to column 15 of the same
line. Note that one might be able to achieve the same
effect with appropriate white space, as in:
.(FIELD "Description: ").
however this will not work if the description is not
initially supplied. This is because when Elec-c
Elec-c
reopens a box comment it removes all trailing white
space, causing a search for "Description: " to fail!


Now that template meets all of the requirements, except for
requirement zero. Requirement 0 is an unwritten requirement
which says that all templates "should be neat, pleasing to the
eye, should not be confusing ..." and many other mighty and lofty
things. I leave it to you to look in "template.c" to see how it
ended up!


Template commands
_________________

Template commands have the following form:

.(COMMAND [parameters ...]).

where:

".(" and ")."delimit the command and its parameter
COMMAND names the template macro to be executed
parameters...are optional parameters to pass to the
template macro

The following template macros are defined:







July 23, 1991 Elec-c
___________________________________
_

-24-
24














BBCM
BBCM
use:
.(BBCM "macro-name").

This macro names a macro to be executed whenever a box
comment is opened. Any parameters given in the string are passed
to the named macro. Your macro will be called after the default
template has been loaded but prior to the word wrap being setup.
The current buffer will be the box comment buffer, this must be
preserved across the call. When your macro exits it should have
the cursor in the column at which it wants word wrapping to wrap
back to. The recommended procedure is to save the cursor
position across the macro call.

You may disable the execution of a "beginning box comment" macro
by either of two methods:
within a template pass an empty string to BBCM:
.(BBCM "").

within a Brief macro invoke the macro "BBCM" and pass
it an empty string as its only parameter:
(BBCM "")

This later technique can be used at the end of your begin-box-
comment macro to make it a "one-shot" deal (i.e., it executes
only once and then removes itself from the scene).


Example:
.(BBCM "beg_mac 1 2 3").

when a box comment is opened "beg_mac" is called with the three
parameters 1,2, and 3.

Note:
Once set this macro is executed every time any box comment
______________
is opened. This is true regardless of whether the box
______
comment contains a template or not.


BOXC
BOXC
use:
.(BOXC col ["tp-name"]).

This macro must only be used in initial files (as it makes no
sense to call for templates being called into a box comment).
When executed it will open a box comment, pull in the named




Elec-c July 23, 1991
______________________
______________

-25-
25














template, and await user input. When the user exits the box
comment it will be aligned beginning at column "col".

Example:
.(BOXC 15 "f").

opens a box comment, reads in template "f", and awaits user
input. Upon exit the box comment will be positioned with its
left most edge at column 15.


DATE
DATE
use:
.(DATE).

This macro inserts the current date in the buffer in the form dd-
month-yyyy.

Example:
.(DATE).

would insert "19-March-1989" if I were to execute it now.


DEF_TP
DEF_TP
use:
.(DEF_TP "tp-name").

This macro designates a default template to be brought into the
box comment buffer whenever a new one is opened.

Example:
.(DEF_TP "r").

cause the template "r" to be read into the box comment buffer
whenever a new box comment is opened. To disable the reading of
a template simply pass an empty string, as follows:
.(DEF_TP "").













July 23, 1991 Elec-c
___________________________________
_

-26-
26














EBCM
EBCM
use:
.(EBCM "macro-name").

This macro names a macro to be executed whenever a box comment is
closed. Any parameters given in the string are passed to the
named macro. Your macro will be called with the current buffer
being that for the .c or .h file being edited and the box comment
transferred into the file. The cursor position will be at the
beginning of the line following the last line of the box comment.

You may disable the execution of an "end box comment" macro by
either of two methods:
within a template pass an empty string to EBCM:
.(EBCM "").

within a Brief macro invoke the macro "EBCM" and pass
it an empty string as its only parameter:
(EBCM "")

This later technique can be used at the end of your end-box-
comment macro to make it a "one-shot" deal (i.e., it executes
only once and then removes itself from the scene).

Example:
.(EBCM "end_mac 1 2 3").

when a box comment is closed "end_mac" is called with the three
parameters 1,2, and 3.

Note:
Once set this macro is executed every time any box comment
______________
is closed. This is true regardless of whether the box
______
comment contains a template.

















Elec-c July 23, 1991
______________________
______________

-27-
27














ENV
ENV
use:
.(ENV "env_name").

This macro inserts the contents of the named environment variable
in the buffer.

Example:
.(ENV "TMP").

would insert the contents of the "TMP" environment variable in
the buffer.


FDRIVE
FDRIVE
use:
.(FDRIVE).

This macro will insert the single drive letter for the current
file in the buffer.

Example:
.(FDRIVE).

would insert "c" in the current buffer if you were editing a file
called "c:\usr\bam\src\tags\main.h".


FEXT
FEXT
use:
.(FEXT).

This macro will insert the current file's extension in the buffer
(only the extension, it does not insert the period).

Example:
.(FEXT).

would insert "h" in the current buffer if you were editing a file
called "c:\usr\bam\src\tags\main.h".











July 23, 1991 Elec-c
___________________________________
_

-28-
28














FIELD
FIELD
use:
.(FIELD "name" [line-move] [column-position]).

This macro defines a template field. Template fields designate
strings which Elec-c will search for to position the cursor to
Elec-c
some convenient point, such as at the beginning of a "Notes"
section in a routine header. The "name" parameter is inserted in
the buffer and saved by Elec-c (along with the optional
Elec-c
parameters) in a list of field definitions. The line-move
parameter gives a relative line movement and the column-position
gives an absolute (note the difference) column position. Here is
how they are used:

to position to a field within a template Elec-c first
Elec-c
searches for the "name" and positions the cursor on it.

if the line-move parameter has been designated then the
cursor is moved (plus or minus) that number of lines.

if the column-position parameter has been given then
the cursor is moved to that column.


Example:
.(FIELD "Description:" 0 15).

will position the cursor to column 15 on the same line that
contains the keyword "Description".

Note: All templates and initial files must have at least
____
one FIELD statement as Elec-c expects to position
Elec-c
the cursor within the template at the first FIELD
statement given.

















Elec-c July 23, 1991
______________________
______________

-29-
29














FINSERT
FINSERT
use:
.(FINSERT "file-name").

This macro will insert the contents of the named file in the
buffer. Note that the file lookup uses _AscFind (the ascending
find macro). This means that the search for the file starts at
the current directory and ascends to root, then looks in
directories named by "BPATH".

Example:
.(FINSERT "copyrite.txt").

would insert the contents of a file called "copyrite.txt".


FNAME
FNAME
use:
.(FNAME).

This macro will insert the name portion of the current file in
the buffer.

Example:
.(FNAME).

would insert "main" in the current buffer if you were editing a
file called "c:\usr\bam\src\tags\main.h".


FPATH
FPATH
use:
.(FPATH).

This macro will insert the path portion of the current file in
the buffer.

Example:
.(FPATH).

would insert "\usr\bam\src\tags" in the current buffer if you
were editing a file called "c:\usr\bam\src\tags\main.h".









July 23, 1991 Elec-c
___________________________________
_

-30-
30














LOWER
LOWER
use:
.(LOWER "string").

This macro converts its string argument to lower case and inserts
the result in the buffer.

Example:
.(LOWER "This is a BIG test!").

would insert "this is a big test!" in the buffer.


TIME
TIME
use:
.(TIME).

This macro inserts the current time in 24 hour format in the
buffer in the form "hh:mm:ss".

Example:
.(TIME).

would insert "23:52:20" if I were to execute it now.


UPPER
UPPER
use:
.(UPPER "string").

This macro converts its string argument to upper case and inserts
the result in the buffer.

Example:
.(UPPER "This is a BIG test!").

would insert "THIS IS A BIG TEST!" in the buffer.



Initializer files
_________________

Elec-c can be told to read in a predefined file when you first
Elec-c
create a .c or .h file. These files, called "initial files" (not
to be confused with your initials file created by the Brief setup
utility), is named in the "brief.ini" file.





Elec-c July 23, 1991
______________________
______________

-31-
31














When you create a new file Elec-c determines if you have
Elec-c
designated an initial file for that file type by checking the
configuration file ("brief.ini"). If designated the file is
located (see "How Elec-c locates files") and read into the new
Elec-c
_________________________
file's buffer. The real power of this features comes from the
fact that it is interpreted as though it were a template. This
means that you can use the template language to obtain customized
starting files "on the fly".


Changing Elec-c parameters
Elec-c
__________________________

Many of the Elec-c parameters can be changed as you edit. This
Elec-c
is done using either F10-"EcSet" (note mixed case) or Alt-F2. In
response Elec-c will present a dialogue box in which the
Elec-c
parameters may be examined and changed (note that the window is
smaller than the number of parameters, you may see additional
parameters by scrolling down through it). To change any
parameter simply select the new value (by typing it in or using
the cursor keys as appropriate to the item) and strike F10 to
save them. Use the escape key to abort.

The alterable parameters are as follows:

Box left edge
_____________
This defines the characters used to draw the left edge
of a box comment.

Box right edge
______________
This defines the characters used to draw the right edge
of a box comment. With this and the "Box left edge"
you can draw attention to important notes:

/********************************************\
!Pay Attention!
!Pay ... You better not cry ... Attention!
!Pay ... You better not pout ... Attention!
!Pay ... I'm telling you why ... Attention!
!Pay Attention!
\********************************************/

Close brace comment col
_______________________
This determines whether Elec-c will comment your
Elec-c
closing braces or not and where these comments will be
positioned. A non-zero value will cause Elec-c to
Elec-c
comment your closing brace with a quick note about what
is being closed. The comment will be positioned




July 23, 1991 Elec-c
___________________________________
_

-32-
32














starting in this column or one tab space to the right
of the closing brace, whichever column is greater.

Closing brace comments can make your code more
readable, especially in really deeply nested sections.
Elec-c puts a simple indicator of the statement type
Elec-c
being closed for the following statement types:
function declarations
_____________________
for loops
_________
while loops
___________
if blocks
_________

Elec-c does not generate these comments for "struct"
Elec-c _________
and "do" blocks.

Examples:
_________

int subr( char *str1 )
{
if ( ... )
{
} /* if() */

while ( ... )
{
} /* while() */
} /* subr() */

Comment column
______________
This defines the column at which comments start.

Comment right margin
____________________
This defines the column at which comments wrap.

Match delay
___________
This gives a value used by Elec-c to delay when showing
Elec-c
you the opening match to a closing brace, bracket, or
parenthesis. Unfortunately Brief does not have a means
of making this processor independent, so you will have
to play with the value until you get one that is to
your liking.

Match up
________
This defines the character sets for which Elec-c will
Elec-c
do match checking. They must be paired as opener-
closer. For example specifying "()" will match only
parenthesis, "[]()" will match brackets and
parenthesis, and "{}[]" will match braces and brackets.



Elec-c July 23, 1991
______________________
______________

-33-
33















Tag file
________
This gives the name of the tag file.

Template file
_____________
This gives the name of the file containing all of the
templates.

Notice delay
____________
Like "match delay" this gives a processor-relative
delay factor. This one is used to determine the delay
during which the copyright notice is displayed when the
Elec-c package is first loaded.
Elec-c

.c use tabs
___________
This indicates whether or not the tab character is to
be used within ".c" files. Values are either "Yes" or
"No".

.h use tabs
___________
This indicates whether or not the tab character is to
be used within ".h" files. Values are either "Yes" or
"No".

.c tabs
_______
This specifies the tab spacing for ".c" files. Set to
some reasonable value (I use 4).

.h tabs
_______
This specifies the tab spacing for ".c" files. Set to
some reasonable value (I use 4).

.c initial file
_______________
This names the file to be read in when a new ".c" file
is created. This file may contain template commands
and will be so processed.

.h initial file
_______________
This names the file to be read in when a new ".h" file
is created. This file may contain template commands
and will be so processed.

.c template file
________________
This names the file to be searched for templates when
editing a ".c" file and Alt-T is struck inside a box
comment.

.h template file
________________



July 23, 1991 Elec-c
___________________________________
_

-34-
34














This names the file to be searched for templates when
editing a ".c" file and Alt-T is struck inside a box
comment.


Reforming code
______________

The reform facility works by using an external utility recently
released into the public domain by Berkeley. This utility,
called "indent", must be in your search path for this facility to
work. Prior to using it you should read the documentation file
which comes with it and setup an "indent.pro" file to your
liking.

When you reform a block Elec-c writes the marked area to a
Elec-c
temporary file in the current directory, sicks indent on it, and
replaces the marked block with the result. The temporary files
used by indent are then deleted.

Elec-c key bindings
Elec-c
___________________

The following key bindings are made by Elec-c:
Elec-c

For normal editing:
___________________
"*" Used to watch for the opening of
*
comments.

"/" Used to watch for the end of comments
/

"" Moves a marked block of text in by one

tab stop.

"" Moves a marked block of text out by one

tab stop.

"{" Used to check if a routine definition is
{
being performed. The closing brace and
a comment naming the routine are
supplied.

"" Ensures that the cursor moves to the

proper indent level to begin the next
line.

"" The Go To Line function now doubles to

go to a tag.





Elec-c July 23, 1991
______________________
______________

-35-
35














"" (Control-Right-Arrow). This positions

you as the start of the next word.

"" (Control-Left-Arrow). Positions you at

the start of the previous word.

")" Shows you the matching open parenthesis
)
and checks to make sure that all
parenthesis and brackets between them
are properly matched (as near as it can
tell anyway).

"]" Shows you the matching open bracket and
]
checks that all parenthesis and brackets
are properly matched in between.

"}" Shows you the matching open brace and
}
checks to make sure that all
parenthesis, brackets, and braces are
properly matched in between. This will
also position the closing brace to the
same column as the first non-blank
character of the line containing the
matching opening brace.

For box comment editing
_______________________

"*" Assigned to self_insert (you cannot
*
create a comment within a comment).

"/" Watches for the closing of the box
/
comment.

"" Deassigned. This prevents you from

switching out of the box comment.

"" Deassigned. This prevents you from

switching out of the box comment.

"" Assigned to the normal goto_line macro.

This prevents you from using the tags
package to switch out of the box
comment.

"" Deassigned. This prevents you from

switching out of the box comment.





July 23, 1991 Elec-c
___________________________________
_

-36-
36














"" Deassigned. This prevents you from

writing out the box comment buffer.

"" Deassigned. This prevents you from

prematurely exiting the box comment.

"" Prompts you for a template name. This

allows you to call in a user defined
template. The template is inserted at
the cursor position and the entire box
comment buffer is "fixed-up".

"{" Assigned to self-insert.
{

"}" Assigned to self-insert.
}

"]" Assigned to self-insert.
]

")" Assigned to self-insert.
)


Files used by Elec-c
Elec-c
____________________

Elec-c requires or uses the following files:
Elec-c

brief.ini Contains configuration data for Elec-c.
Elec-c
_________
This file must be in the Elec-c search
Elec-c
path.

1 ctags Contains tag definitions. This file is
_____
produced by the tags program included
____
with the Elec-c package. This file may
Elec-c
be located anywhere in the Elec-c search
Elec-c
path.

elec-c.dlg Contains the dialogue box definition for
__________
the "EcSet" macro (Alt-F2). This must
be in the same directory that your Brief
help files are located (refer to your
Brief installation if you are unsure of
what directory this is).

1 template.c Contains the template definitions. This
__________
file may be located anywhere within the
Elec-c search path.
Elec-c

Notes:




Elec-c July 23, 1991
______________________
______________

-37-
37














1 These are the default file names, they may be changed
via ALT-F2 or ALT-F10-EcSet.
______ _____________


How Elec-c locates files
Elec-c
________________________

Elec-c searches for most of its data files using the "Ascending
Elec-c
Find" macro (see ASCFIND.M). This means that it will use the
_________
first occurrence that it finds of the file along the following
search path:

1) the current directory is searched first
2) the next higher directory is searched next
3) the directory ascent continues until the root
(top most) directory has been searched).
4) the directory path given by "BPATH" is searched
BPATH
last.

This search strategy was chosen to match the project oriented
environments in which Elec-c is typically used. Consider a
Elec-c
software house which is developing programs for a number of
companies. At the top-most directory are the client
subdirectories. Each of these has, perhaps, individual
template.c and copyrite files. Within a client directory are the
project directories active for that client. In turn each project
directory contains a directory for every major component for that
project, each of which may have their own ctags file or have a
master ctags file at one or more higher nodes in the tree.























July 23, 1991 Elec-c
___________________________________
_

-38-
38















Should you need to contact me I suggest any of the following:

By E-Mail:
Compuserve: 72240,3115
GEnie: B.Mallett


By US-Mail:

M-Tek
P.O. Box 855
Derry, N.H. 03038
Attn: Bruce A. Mallett





































Elec-c July 23, 1991
______________________
______________

-39-
39