CBM Funet Archive/cbm-funet-archive-2003.iso/cpm/editors/z80emacs.pma/MAPKEYS.DOC

Text File | 1979-12-31 | 10KB | 223 lines

"bINDING" IS ONE OF THOSE WORDS OF EMACS JARGON THAT MIGHT

BE BOTHERSOME, BUT WE HAVE TO USE IT.



tHE IDEA IS THAT AN EDITOR CONTAINS A CERTAIN SET OF COMMANDS,

WHICH ARE ALWAYS THE SAME COMMANDS NO MATTER WHAT KEYSTROKES ARE

USED TO INVOKE THEM. tHE ASSOCIATION OF A KEYSTROKE TO A

COMMAND IS CALLED A "BINDING".



eDITORS DERIVED FROM EMACS HAVE AN INTERNAL STRUCTURE THAT MAKES

IT EASY TO CHANGE THE BINDINGS ( UNLIKE wORDsTAR OR vde ).



oN A BIG COMPUTER, YOU CAN CHANGE EMACS BINDINGS ONLINE; BUT Z80EMACS

HAS TO FIT IN 64kb, SO THE BINDINGS ARE DONE OFFLINE.



z80EMACS COMES WITH A DEFAULT SET OF BINDINGS ALREADY INSTALLED.

tHESE BINDINGS ARE JUST FINE FOR THE TERMINAL i USE, BUT YOU

PROBABLY WILL WANT TO CHANGE THEM IN YOUR COPY OF THE PROGRAM.



hERE'S HOW:



fIRST, MAKE SURE YOU HAVE A COPY ( not YOUR ONLY COPY! ) OF me.com

ON YOUR CURRENT DISK AND USER AREA; MAKE SURE YOU HAVE zmecmds.lst,

me.sym, mapkeys.com, AND meconfig.com.



tAKE A LOOK AT zmecmds.lst, BUT DON'T CHANGE IT!

tHIS FILE CONTAINS A LIST OF THE NAMES OF ALL THE COMMANDS IN

Z80EMACS, AND FOR EACH COMMAND THERE IS A NUMBER.



tHE COMMAND NAMES ARE IN THE FORMAT OF THE uecs ( uNIVERSAL eDITOR

cOMMAND sET ), VERSION 1.0; EACH NAME STARTS WITH A PREFIX

THAT ASSIGNS THE COMMAND TO A CLASS OF COMMANDS.



iN ORDER TO CUSTOMIZE THE BINDINGS, YOU WILL HAVE TO RUN TWO PROGRAMS,

FIRST mapkeys.com AND THEN meconfig.com.



mapkeys.com WILL READ THE zmecmds.lst FILE AS PART OF ITS PROCESSING.

aNOTHER PART OF ITS PROCESSING WILL BE TO READ THE KEYBOARD, AND

YOU'LL BE TYPING IN THESE NAMES. fORTUNATELY, YOU WON'T HAVE TO TYPE

IN THE WHOLE NAME ( AS WE'LL SEE LATER ).



meconfig.com WILL READ A FILE PRODUCED BY mapkeys ( maptable.zme ),

WILL READ me.com AND me.sym, AND WILL WRITE THE NEW BINDINGS OUT TO me.

com. iT INSTALLS THE BINDINGS BY PATCHING THEM INTO THE PROGRAM.



======================================================

=                                                    =

= using mapkeys.com                                  =

=                                                    =

======================================================



aFTER YOU START mapkeys, IT WILL TELL YOU HOW MANY LINES IT READ FROM

zmecmds.lst, AND THEN ASK YOU TO "eNTER A NAME: ".



iF YOU JUST HIT return, IT WILL LIST ALL THE COMMANDS, ONE SCREENFUL

AT A TIME, WITH "[rETURN TO CONTINUE]".



tRY TYPING "WORD" AT THIS PROMPT ( LEAVE OUT THE QUOTES, HIT return

AT THE END OF IT ). mapkeys WILL LIST FOR YOU ABOUT 9 COMMANDS THAT

INCLUDE THE WORD "wORD", AND TELL YOU HOW MANY COMMANDS IT MATCHED.

nEAT STUFF, HUH?



iF YOU MANAGE TO MATCH EXACTLY ONE NAME, mapkeys WILL PROMPT YOU TO

"eNTER A KEYSTROKE SEQUENCE: ".



yOU CAN JUST TYPE THE SEQUENCE THAT YOU WANT TO USE TO INVOKE THE

COMMAND, AND THEN HIT return. tHIS IS EASY ENOUGH, BUT HOW DO YOU

MAP SOMETHING TO return? OR TO linefeed?



aHA, THERE'S A TRICK! i FIGURED THAT YOU WOULDN'T WANT TO MAP THE

CARAT ( "^" ) TO ANYTHING ELSE ( IN FACT YOU CAN'T, AS i'LL EXPLAIN

LATER WHEN i TELL YOU WHAT YOU can'T MAP ), SO:



    iF YOU TYPE "^m" ( A CARAT AND AN m ), mapkeys INTERPRETS IT

    AS MEANING ^m ( CONTROL-m, OR CARRIAGE RETURN ).



aT THE "eNTER A KEYSTROKE SEQUENCE: " PROMPT, IF YOU DON'T WANT TO

MAKE A NEW MAPPING FOR THIS COMMAND AFTER ALL, JUST HIT return RIGHT

AWAY.



tHERE'S ONE MORE TRICK YOU NEED TO KNOW ABOUT: HOW TO unmap A KEY!



tHE PROBLEM IS THIS: THERE IS A PREDEFINED AMOUNT OF SPACE ALLOCATED

FOR THE COMMAND DISPATCH TABLES. iF YOU MAP ^j TO SOMETHING, meconfig

WILL SEE THAT ^j USED TO BE MAPPED TO SOMETHING ELSE, AND WILL

FREE UP THE SLOT IN THE TABLE THAT WAS USED BY THE OLD MAPPING.



bUT, IF YOU MAP ^x^j TO SOMETHING, YOU'VE USED UP ONE OF THE EMPTY

SLOTS! sUPPOSE YOU MAP IT TO ec-wORD-fORW; meconfig DOES not ASSUME

THAT YOU WANT TO UNMAP ^f; IT'S LEGITIMATE TO HAVE MORE THAN ONE

SEQUENCE BOUND TO THE SAME COMMAND!



tO KEEP FROM RUNNING OUT OF SLOTS IN THE TABLE, YOU MAY HAVE TO

EXPLICITLY unmap SOME SEQUENCES BY MAPPING THEM TO

"uNDEFINED-fUNCTION".



======================================================

=                                                    =

= what's a "sequence"; what you can't do             =

=                                                    =

======================================================



iN THE STANDARD EMACS COMMAND-SPACE, THERE ARE 384 POSSIBLE

SEQUENCES OF KEYSTROKES THAT COULD BE MAPPED TO COMMANDS.

( BUT ONLY 382 SEQUENCES ).



fIRST OF ALL, THERE ARE THE 128 NORMAL ascii CHARACTERS.

iN ANY PROPER EMACS, THEY ARE ALL MAPPABLE; BUT IN ORDER TO BE

ABLE TO KEEP UP WITH YOUR FLYING FINGERS, Z80EMACS HAD TO MAKE

A FEW COMPROMISES; FOUR SPECIAL CHARACTERS, ^u, ^\, ^x, AND escape,

ARE HARDCODED IN THE PROGRAM, AND CAN'T BE REASSIGNED

( THIS DEFECT CAME WITH THE ORIGINAL MICROEMACS CODE ),

AND THE PRINTABLE CHARACTERS ARE ALL FORCED TO BE SELF-INSERTING

( TYPE AN 'a', GET AN 'a' IN THE FILE ).



sECONDLY, THERE ARE 128 "META-CHARACTERS", WHICH YOU TYPE BY

HITTING escape AND THEN HITTING ANY OF THE 128 NORMAL ascii

CHARACTERS.



tHIRD AND LAST, THERE ARE 128 "CONTROL-x" CHARACTERS, THAT YOU

ENTER BY HITTING ^x AND THEN SOMETHING ELSE.



bY THE WAY, LHE OTHER SPECIAL CHARACTERS i MENTIONED,

CONTROL-u AND CONTROL-\, ARE USED WHEN YOU WANT TO START TYPING IN

A NUMERICAL ARGUMENT TO FEED TO THE NEXT REGULAR COMMAND.



tHUS, THERE ARE 284 DIFFERENT COMMAND SEQUENCES THAT CAN BE

REMAPPED, WHICH MAKES Z80EMACS PRETTY WELL CUSTOMIZABLE, THOUGH

NOT PERFECTLY SO.



tHERE ARE ONLY 67 OR SO COMMANDS THAT YOU CAN ASSIGN TO THESE

380 COMMAND SEQUENCES, SO MOST SEQUENCES WILL BE UNDEFINED.

tHE COMMAND SPACE IS MUCH LARGER THAN THE NUMBER OF COMMANDS, SO

MULTIPLE MAPPINGS ARE SENSIBLE; A MULTIPLE MAPPING IS WHERE YOU

HAVE TWO OR MORE SEQUENCES BOUND TO THE SAME COMMAND, IN OTHER WORDS,

MORE THAN ONE WAY TO DO THE SAME THING.



oNLY 4 OF THE COMMANDS ARE BUILT IN TO THE ROOT SEGMENT, AND ALWAYS

STAY IN MEMORY: ^g ( ci-aBORT-cANCEL ), RIGHT ARROW, LEFT ARROW, AND

SELF-INSERT; SELF-INSERT ISN'T IN THE INTERNAL DISPATCH TABLE,

AND THERE IS ONLY ONE FREE SLOT IN THIS TABLE

( THIS IS RELEVANT TO THE DISCUSSION ABOUT RUNNING OUT OF SLOTS; SEE ABOVE ).



aLL THE OTHER COMMANDS LIVE IN OVERLAYS, AND THEIR DISPATCH TABLE HAS

5 EXTRA ENTRIES. a FEW COMMANDS ALREADY HAVE MULTIPLE SEQUENCES IN

THE DEFAULT MAPPING ( THIS IS BECAUSE SOME ascii TEMINALS SEND ^j

FOR DOWN-ARROW, BUT OTHERS SEND ^v ).



iF YOU'RE RUNNING OUT OF SPACE IN THE OVERLAY DISPATCH TABLE BECAUSE

YOU ARE MAKING LOTS OF MULTIPLE MAPPINGS, THERE ARE COMMANDS YOU CAN

GET RID OF:

"DEBLANK",

"LOWERCASE REGION", "UPPERCASE REGION",

"PREVIOUS WINDOW" ( "NEXT WINDOW" IS GOOD ENOUGH, YOU WON'T HAVE SO

MANY WINDOWS THAT YOU NEED A "PREVIOUS WINDOW" COMMAND ),

"SHRINK WINDOW" ( YOU CAN ALWAYS CHANGE TO THE OTHER WINDOW AND ENLARGE IT ),

"SCROLL DOWN WINDOW" ( YOU CAN HIT ^\^x^k, "SCROLL UP" WITH A NEGATIVE

PARAMETER ),

"SCROLL UP WINDOW" ( TO SAVE SPACE, Z80EMACS DOESN'T DO FANCY SCREEN

UPDATING, SO THE SCROLLING COMMANDS AREN'T TOO GREAT ),

"CAPITALIZE WORD", "LOWERCASE WORD", "UPPERCASE WORD".



======================================================

=                                                    =

= choosing a mapping; why the default is so awful    =

=                                                    =

======================================================



iF YOU'RE USED TO ANY OF THE SEVERAL STANDARD INCOMPATIBLE

FORMS OF EMACS, THE DEFAULT MAPPING IS AWFUL BECAUSE IT ISN'T

LIKE THE ONE YOU'RE USED TO.



tHE DEFAULT MAPPING IS A COMPROMISE BETWEEN A NEWFANGLED

"THEORETICALLY BEST" MAPPING i ALMOST FINISHED WORKING OUT,

AND AN OLDFASHIONED DESIRE TO BE ABLE TO USE ALL THE FANCY

KEYS ON THE TERMINAL i USED WHILE DEVELOPING Z80EMACS.

i SHOULD CLEAN THIS UP, OF COURSE...



tHE COMMANDS LABELED zmap IN "MAPPING.H" ARE THEORETICAL;

THE THEORETICAL MAPPING IS A COMPROMISE BETWEEN ERGONOMICS

( FREQUENTLY-USED COMMANDS ARE EASY TO TYPE, A CONSIDERATION

THAT MOST EMACS COMMAND SETS OVERLOOKED; FOR EXAMPLE, MOST

EMACSES USE m-F FOR WORD FORWARDS, m-V FOR PAGE BACK ),

AND MNEMONICS ( LESS-OFTEN-USED COMMANDS TRY TO BE EASIER TO

REMEMBER ).



tHE COMMANDS WITH tvi IN THEIR COMMENTS ARE BASED ON MY FUNCTION

KEYS.



sEVERAL USEFUL CONTROL KEYS WERE LEFT UNMAPPED:



^a BECAUSE i THOUGHT i MIGHT PUT IN "MAGIC MODE", SO i COULD USE

THE funct KEY ON MY TERMINAL,



^q AND ^s BECAUSE LOTS OF TERMINALS EAT THESE,

( IF YOU CAN USE ^q, PLEASE DON'T MAKE IT "QUOTE" AS EMACS DOES;

IT'S SO STUPID TO USE UP AN EASY-TO-TYPE CHARACTER FOR A

RARELY-USED COMMAND ),



^w SHOULD PROBABLY BE ZMAP FOR DELETE-WORD-FORWARD,



^] AND ^_ COULD BE USED FOR ANYTHING YOU WANT.



tO CHOOSE YOUR OWN MAPPING, i RECOMMEND THAT YOU TRY KEEPING zmap

COMMANDS AS THEY ARE, AND REMAP THE tvi COMMANDS TO WHATEVER YOUR

TERMINAL DOES.



oF COURSE, IF YOUR TERMINAL SENDS ^[[a FOR UP-ARROW, YOU'RE OUT OF

LUCK. iF THERE'S EVER ANOTHER RELEASE, THIS SHOULD BE FIXED.



======================================================

=                                                    =

= printing out what mapping you installed            =

=                                                    =

======================================================



tHERE SHOULD BE A PROGRAM TO READ me.com AND REPORT ON THE

INSTALLED MAPPING; THERE ISN'T.



hAVE FUN,



rALPH bETZA,oCTOBER 4, 1991