HELP EMACS					Richard Caley 18th January 1991

Running pop11 under gnu emacs.

Keywords: VED, emacs

This help file describes software which gives user of the Free
Software Foundation's `emacs' editor ( `gnuemacs' ) similar facilities
to those available in the builtin Poplog editor Ved.

An alternative way for an emacs user to use poplog without having to
learn a new editor is provided by the `VEDEMACS' library which changes
the keystrokes and commands of Ved to be close to those of emacs. See
HELP *VEDEMACS.

CONTENTS - (Use <ENTER> g to access sections)

 -- Setting up POPLOG to run under EMACS
 -- Setting up EMACS to understand pop11
 -- Running pop11 under EMACS
 -- Pop-mode, editing pop11 in emacs
 -- Reading POPLOG help files in emacs
 -- Related Documentation
 -- Who to blame

-- Setting up POPLOG to run under EMACS ------------------------------

Since POPLOG makes some assumptions about its environment when it
starts up, it is necessary to tell it that it is not talking to a
normal terminal, but to emacs. This is done by loading the library
`pop_for_emacs' from your init.p (see HELP *INIT). You really only
want to do this when running POPLOG under emacs, you can tell if you
are by looking at the environment variable `TERM'. as follows --

	if systranslate('$TERM') = 'emacs' then
	    loadlib('pop_for_emacs');
	endif;

-- Setting up EMACS to understand pop11 ------------------------------

Emacs, by default, knows nothing about pop11 or poplog. To use the
facilities described here you must add some information to the file
`.emacs'  in your home directory.

There are three things to tell emacs about pop11. First you must tell
it how to recognise pop11 program files. You do this by telling if
that any file ending `.p' should be treated as pop11 --

    (setq auto-mode-alist 
         (append
          '(("\\.p$"   . pop-mode))
           auto-mode-alist))

Next you must tell emacs about your system and your personal
preferences. There are a number of emacs variables you can change to
control how pop-mode works, and some which tell it where to find
things. Here are a few I use --

	(setq pop-short-help-commands t)	; I like short commands
	(setq pop-use-pl1-comments nil)		; I don't use /*...*/
						; inside procedures

Other variables which you may want to change are:

	pop-mode-hook, pop-label-regexp, pop-declaration-indent-step,
	pop-label-indent, pop-indentation-info, pop-declaration-starters,
	pop-declaration-modifiers, pop-interesting-declaration-modifiers,
	pop-definition-starters, pop-definition-enders,
	pop-open-close-assoc pop-path

Use the emacs ^Hv command to find out more.

Finally you must tell it where to find the programs which define the
commands you wish to use. The most useful commands are `pop-mode'
which turns on pop11 mode (and which will be done on any `.p' file)
and `run-pop' which starts pop11.  These are defined in the files
`pop-mode' and 'inferior-pop-mode' respectively so add the following
to your `.emacs' --

	(autoload 'pop-mode "pop-mode" "Set pop11 mode" t nil)
	(autoload 'run-pop  "inferior-pop-mode" "Run a poplog process" t nil)

for reading help files, you can either use short or long help commands
to emacs depending how you set `pop-short-help-commands' if it is `t'
add...

	(autoload 'help "pop-sys-file-mode" "Get poplog Help" t nil)
	(autoload 'ref "pop-sys-file-mode" "Get poplog Ref file" t nil)
	(autoload 'doc "pop-sys-file-mode" "Get poplog Doc file" t nil)
	(autoload 'teach "pop-sys-file-mode" "Get poplog Teach file" t nil)
	(autoload 'showlib "pop-sys-file-mode" "Get poplog library file" t nil)

if it is `nil', meaning use the long commands do

	(autoload 'pop-help "pop-sys-file-mode" "Get poplog Help" t nil)
	(autoload 'pop-ref "pop-sys-file-mode" "Get poplog Ref file" t nil)
	(autoload 'pop-doc "pop-sys-file-mode" "Get poplog Doc file" t nil)
	(autoload 'pop-teach "pop-sys-file-mode" "Get poplog Teach file" t nil)
	(autoload 'pop-showlib "pop-sys-file-mode" "Get poplog library file" t nil)

-- Running pop11 under EMACS ---------------------------------------

When you have told poplog about emacs and emacs about poplog, you can
start up an emacs and a pop11.

How you run emacs will depend upon your system. I just type `emacs'
some may have to type `gnuemacs' if all else fails consult your local
guru. 

If you are unfamiliar with gnu-emacs, read the emacs online tutorial,
type `control-h t', this is a very good introduction to using emacs.

Ok, now type the command 

	M-x run-pop

(if you don't understand, go and really read the tutorial this time:-).

This will put you in a window called `*pop-11*' in which there should
be a normal pop11 session.

-- Pop-mode, editing pop11 in emacs ----------------------------------

If you begin to edit a file whose name ends in `.p', emacs should put
you into pop11 mode (it will show `Pop11' on the mode line). 

In this mode you can type pop11 code and have it be indented
correctly, just type a single `TAB' character to indent the current
line; alternatively you can use the line-feed character instead of
return to start a new line with the cursor indented correctly. When
you type a semicolon, emacs will check that the lie is correctly
indented too.

The emacs movement commands M-p, M-n, M-C-a etc know about pop11
syntax and will move you around the current procedure a construct at a
time. The sequence M-C-a M-C-q will re-indent the entire procedure.

You can use the key sequence M-] (closeit) to close the last open
pop11 construct. Thus if your code looked like this --

	define macro lvars foo (x)
	
	    lvars x;

	    repeat x times
	        'hello'=> [=]


where [=] is the cursor, you can type M-] and emacs will insert the
`endrepeat', correctly indented --

	define macro lvars foo (x)

	    lvars x;

	    repeat x times
		'hello'=> 
	    endrepeat;[=]

typing M-] again closes the define --

	define macro lvars foo (x)

	    lvars x;

	    repeat x times
		'hello'=> 
	    endrepeat;
	enddefine;    ;;;  macro foo[=]

The comment was inserted automatically.

When you have some code and you wish to load it into pop11, use one of
the commands

	C-cC-r	- load region
	C-cC-p  - load current procedure
	C-cC-b  - load the entire buffer

The code will be loaded into the pop11 you started earlier and you
will see the results there. The command M-C-x is a synonym for C-cC-p
for lisp hackers who have wandered into the wrong language...

-- Reading POPLOG help files in emacs --------------------------------

The commands for reading poplog help from emacs are of two types,
short and long. The commands have the same effect, but the names are
different. By default the following commands are available

	M-x pop-help
	M-x pop-ref
	M-x pop-doc
	M-x pop-teach
	M-x pop-ploghelp
	M-x pop-showlib

If you have set the variable `pop-short-help-commands' to `t' in your
.emacs file the commands will not have the `pop-' prefix. The default
is long names so that non poplog people can use the commands without
having their emacs session do weird things.

Unlike VED's help system, these commands keep only one file of poplog
help file (in each category) in emacs at a time. Asking for a new help
file will replace the old one with a new one. If you wish to retain a
help file for future reference type `s' and it will be given its own
buffer. I like this because it means that I can look through lots of
help files without filling my emacs with junk.

The normal poplog cross reference following facilities are available.
Typing `M-n' will find the next cross reference in the file and `M-h'
will follow that reference. The characters `/' and `?' are synonyms
for these commands. Typing M-h in pop-mode will give help on the
pop11 word the cursor is on, if such exists.

The command `M-g' is similar to the Ved command <ENTER>g (see HELP
*VED_G), it allows you to step through a help file a section at a
time. 

-- Related Documentation ---------------------------------------------

See also:
    HELP *VED      - The poplog builtin editor.
    HELP *VEDEMACS - How to make VED look like emacs.
    HELP *JUSTIFY  - indentation in VED, pop-mode tries to be similar.

Also, see the emacs `info' help system, accessed by typing `control-h i'
to emacs, for more information on emacs.

-- Who to blame ------------------------------------------------------

This is all basically my fault. I like emacs, I don't like VED and
this is the result. Mail any comments, fixes or bug reports to 

	R.Caley@ed.ac.uk

This whole package is distributed under the terms of the GNU General
Public Licence, which means you can do what you like with it except
distribute it without source code. If you can work out what the
`object' code is for a help file you are a better bod than me. You
probably want to leave my name on it anyway, after all you wouldn't
want to be blamed.
