NeWS support for GNU Emacs					4 Sep 1988

This note describes how to obtain, install and use the NeWS interface
for GNU Emacs.  Prerequisites for installation of this package are:

	GNU Emacs version 18.49, 18.50, 18.51, or 18.52
	NeWS 1.0 or 1.1
	The patch(1) program, or familiarity with the UNIX diff(1) utility

Because of portability bugs in the NeWS cps library, the NeWS 1.0 interface may
not work on some non-Sun hardware/software configurations.  For example, it
will not work with an unmodified NeWS 1.0 cps library under Ultrix or 4.3bsd on
the vax.  Contact chris@columbia.edu if you need help fixing your cps library.

* Obtaining the NeWS interface for GNU Emacs

The NeWS interface is available on the Internet via ftp and electronic mail.

To retrieve the NeWS interface via email, send a message containing the line
"send NeWS emacs-support" to archive-server@columbia.edu.  You will receive a
large message (approximately 70k characters in size) by return mail.  Save the
body of the return message (excluding the mail headers) to a file named
ps-emacs.shar and extract its contents into an empty directory using the
command "sh ps-emacs.shar".

If you have access to Internet ftp, use "binary mode" anonymous ftp to retrieve
the file ps-emacs.tar.Z from the "pub" directory on host columbia.edu.  Extract
the contents of this file into an empty directory using the command
"zcat ps-emacs.tar.Z | tar xf -".

* Installing the NeWS interface

The NeWS interface consists of two new C source files, two Emacs-Lisp library
files, and a small set of patches to other source files.  In the text below,
"$EMACS" refers to the top-level directory containing the Emacs sources, lisp
libraries, documentation, etc.

If you're starting with a fresh copy of the Emacs sources, you may wish to
build and test Emacs once without the NeWS interface.  If you elect to do this,
you can save some time by adding the line "#define HAVE_NEWS" to config.h (in
addition to any other changes) before you run "make" for the first time.
Subsequent "make" runs will then only need to recompile the files which
contain changes specific to the NeWS interface.

First, install the new files into their proper locations within the Emacs
source tree:

	Move the files NeWS.c and NeWS.cps into the $EMACS/src directory.
	Move postscript.el into the $EMACS/lisp directory.
	Move NeWS-win.el into the $EMACS/lisp/term directory.

Next, apply the changes specified in the file "ps-emacs-diffs".  The affected
files are dispnew.c, emacs.c, keyboard.c, process.c, and ymakefile.  If you
have the patch(1) program, the patches can be applied with the command

	patch -d $EMACS/src < ps-emacs-diffs

Examine the output from patch to be sure that no errors have occurred.  These
diffs are "context diffs" generated from the 18.51 sources; the patches
themselves have not changed since 18.49 (except for ymakefile, which required a
change for NeWS 1.1), so you can probably ignore this step if you're simply
updating an older version of Emacs to which these changes have already been
applied.

If you don't have patch(1), or patch fails for one reason or another, carefully
apply the changes by hand, saving the original files in case you need to back
out the changes.  The line numbers may be off somewhat if you've modified the
Emacs sources yourself, or you're installing these patches into an older
version of Emacs.

Next, edit the file "config.h" and add the line "#define HAVE_NEWS" if
you haven't already done so.  If you later wish to build Emacs without NeWS
support, you can simply comment out this line rather than pulling out the
individual patches.  (You can build Emacs with any combination of NeWS, X,
or SunView support, if you use more than one window system).

Consult the file $EMACS/src/ymakefile and correct the pathnames for the
"cps" program and "libcps.a" if they are not correct for your system.

Finally, rebuild Emacs and test the resulting executable.

If xemacs fails to start properly, first check to make sure that NeWS-win.el is
properly located in $EMACS/lisp/term/NeWS-win.el.  If that's not the problem,
try invoking Emacs with different options to try to rule out some other
possibilities:

	# does Emacs work normally with the NeWS interface disabled?
	emacs -nw
	# is there a problem with a NeWS-setup-hook in user's .emacs file?
	emacs -q
	# is there a problem with the default startup behavior?
	emacs -origin 0 0
	emacs -reshape

If all else fails, send mail to chris@columbia.edu for help, describing your
observations and your hardware and software environment in as much detail as
possible.

* Using the GNU Emacs NeWS interface

Emacs will automatically create a new NeWS window if the environment variable
"NEWSSERVER" is set; you can start up a "normal" Emacs in your terminal
emulator window by specifing the "-nw" option on the command line.

By default, Emacs initially prompts the user with an outline of a 24x80
character window and waits for the user to position the outline and press a
mouse button.  This behavior is somewhat different from the convention used by
other NeWS applications; if you don't like it you can change it using command
line options or function calls in a NeWS-setup-hook as described below.  Note
that Emacs will appear to hang if errors occur while running a user-specified
NeWS-setup-hook.

When invoked under NeWS, Emacs accepts the following additional command line
arguments:

    -origin x y		Create a fixed-size window at position (x,y)
    -xy x y		in the root window's coordinate system.

    -dimensions c r	Create a window c columns wide and r rows high.
    -size c r		The user is prompted for the windows initial position
			as described above.

    -framelabel	str	Set the Emacs window's frame label to "str"
    -fl str

    -drag		(default) At startup, present the user with an outline
			of a default-size Emacs window which tracks the mouse
			position until the user presses a mouse button.
			
    -reshape		At startup, prompt the user for the upper-right and
			lower-left corners of the Emacs window; the size of
			the NeWS window determines the number of rows and
			columns that Emacs will use (not the size of the font).

In addition to these command line arguments, the user may specify defaults
by defining a "NeWS-setup-hook" in his or her .emacs file.  For example,

    (setq NeWS-setup-hook
	'(lambda nil
	   (NeWS-set-dimensions 80 40)	; use a 40-line window
	   (NeWS-set-origin 100 100)))	; fix it at position (100,100)
	   
In addition to putting commands inside NeWS-setup-hook, you can also
execute commands conditionally by testing the "window-system" variable:

	(if (eq window-system 'NeWS)
	    (...))

The following functions are legal in the context of the NeWS-setup-hook:

    (NeWS-set-font "Courier" 12)	Specify the name and size of the font
					to be used.  Only fixed-width fonts
					are supported.

    (NeWS-reshape-window)		Reshape the window using the mouse to
					select the upper-left and lower-right
					corners of the new window.

    (NeWS-set-origin x y)		Set the origin of the Emacs window,
					relative to the root window coordinate
					system.  0,0 is the lower-left corner.

    (NeWS-set-dimensions c r)		Set the screen width and height (in
					characters) to c and r, respectively.

    (NeWS-set-framelabel "string")	Set the Emacs window's frame label.

    (NeWS-set-input-policy t)		If arg non-nil, "pasting" text into an
					Emacs window simulates typein rather
					than simply inserting text.

    (NeWS-option-drag)			Same as command line -drag option
    (NeWS-option-reshape)		Same as command line -reshape option

    (NeWS-set-window-retained t)	If arg non-nil, use a "retained canvas"
					for the Emacs window.  See the NeWS
					manual for details on retained windows.

    (NeWS-set-i&d-line-ok nil)		These three functions specify whether
    (NeWS-set-i&d-char-ok nil)		or not Emacs should display hardware
    (NeWS-set-scroll-region-ok nil)	to scroll, insert, and delete text.
					The optimal settings will depend on
					personal preferance, display hardware
					performance, and whether or not the
					Emacs window is "retained".

Additional functions you can invoke from your own lisp code include:

    (NeWS-set-selection rank size str)	Make a string available as a NeWS
					"selection" to other NeWS clients.
					I don't have any Sun manuals so
					I'm not sure what appropriate values
					are for rank and size.

    (NeWS-put-region)			Copy the text between point and
					mark to the NeWS "Shelf Selection".

    (NeWS-put-text "string")		Copy "string" to the Shelf Selection.

    (NeWS-get-text)			Insert, or treat as character input,
					the contents of the Shelf Selection.
					[Should return a string!]

The following M-x commands can be invoked interactively:

    M-x NeWS-set-dimensions		See the descriptions of these
    M-x NeWS-set-font			functions above.
    M-x NeWS-set-framelabel
    M-x NeWS-set-origin
    M-x NeWS-get-text
    M-x NeWS-put-region
    M-x NeWS-set-input-policy
    M-x NeWS-reshape-window
    M-x NeWS-set-i&d-char-ok
    M-x NeWS-set-i&d-line-ok
    M-x NeWS-set-scroll-region-ok
    M-x NeWS-set-window-retained

* Keyboard Support

Support for non-liteUI clients is there, but hasn't been tested.  The Meta key
and function keys (under liteUI) are supported, although no keymap is
provided to interpret the escape sequences generated by the NeWS server.  No
special consideration is made for autorepeat under NeWS 1.0, but I assume that
the autorepeat mechanism posted to the net will work.

* Mouse Support

The mouse is not supported directly; instead, a simple interface to the liteUI
selection mechanism is provided.  Currently, the left and middle buttons act
much as they do in psterm, except that they also change the cursor position: to
make a selection, mark one end of the text with the left button, then extend it
in either direction using the middle button and use the Put key (usually L6, on
Sun keyboards) to copy the selection to the "shelf" and so on.  Note that
pasting large amounts of text into some applications may be fatal to the
destination program; Emacs itself can handle up to about 4000 characters at a
time, and will ignore larger selections.

Clicking the left and middle mouse buttons in the minibuffer does nothing
useful; clicking the left and middle buttons a buffers mode line invokes
"scroll-up" and "scroll-down", respectively.

* Menu Support

No explicit menu support is provided, but you can create menu items using the
"NeWS-send-PostScript" routine.  For example, the following elisp code adds an
"Rmail" item to the main menu:

    (NeWS-send-PostScript "0 (Rmail) {(rmail) emacscmd}
			/insertitem window /FrameMenu get send" nil)

The "emacscmd" PostScript procedure removes a string representing an elisp
function call from the stack and queues it for execution by Emacs;
"emacsinput" is similar but simulates typein.  You can store keyword/value
pairs in Emacs's dictionary (e.g. to create pull-right menus) but beware
naming conflicts and side effects in your PostScript code.

A foolproof, easy-to-use menu interface will be available eventually.

* PostScript Mode -- postscript.el

PostScript Mode is a simple "major mode" for editing PostScript code.  In
addition to binding some syntax-hacking functions to various keys, the C-c !
and C-c C-c commands provide useful interactive and non-interactive interfaces
to psh.

See the top of postscript.el for instructions on how to ask Emacs to invoke
postscript-mode automatically whenever you visit PostScript files.

* Bugs

If you want to use the Courier font in the 10 point size, you may need to put

	(NeWS-send-PostScript "true setprintermatch" nil)

in NeWS-setup-hook after changing the font, in order to fix a problem with the
"|" character's width.  You'll have to set "printermatch" to false before
subsequently resizing the window or changing fonts again, though, in order
to avoid confusing Emacs' font metric calculations.

The NeWS window blinks when Emacs starts up.  Setting the lisp variable
"inhibit-startup-message" to "t" will avoid this.

The NeWS interface for Emacs makes extensive and somewhat clumsy use of the
NeWS "copyarea" primitive, with the following implications:

	The use of insert/delete-line and scroll regions may be noticably
	slower when the window is retained.
	
	The use of any insert/delete-char/line functions may require
	annoying screen refreshes when part of the window is obscured
	if the window is NOT retained.

Most of the functions which induce annoying screen refreshes can be disabled if
it's not desirable to have the window retained, but Emacs may still use
insert/delete-char operations regardless of how the options are set.  This will
probably be fixed eventually, but in the meantime you may want to experiment
with the options; the values you should use may depend on the capabilities of
your display hardware.

* Bug Reports

Please send any comments, questions, bug reports or fixes to:

    chris@columbia.edu (Internet) or ...!rutgers!columbia!chris (UUCP)

