Distribution Notes for Win-Emacs 1.35

Copyright (c) 1993, 1994 Pearl Software, Emeryville, CA.

   Win-Emacs is a Microsoft Windows version of the popular and powerful
editor GNU Emacs and also includes ports of grep, diff, and patch.
Win-Emacs is produced by Pearl Software.

License
*******

   Pearl Software has ported GNU Emacs to Windows.  To run, it requires
an X Windows emulation package.  One such emulation package, WIN-X, is
provided on this disk.  WIN-X is Pearl proprietary.  The license
agreement for the proprietary WIN-X package may be found in the file
`license.txt' after installation.

     THE FREE SOFTWARE FOUNDATION'S GNU EMACS IS PROVIDED AT NO CHARGE
     UNDER THE TERMS OF THE FREE SOFTWARE FOUNDATION'S GENERAL PUBLIC
     LICENSE.  THE GENERAL PUBLIC LICENSE MAY BE VIEWED BY INSTALLING
     THE SOFTWARE AND TYPING `CONTROL-H' FOLLOWED BY `CONTROL-C' OR BY
     VIEWING THE FILE `COPYING' IN THE `info' DIRECTORY AFTER
     INSTALLATION.

   The reason we consider WIN-X and GNU Emacs two separate programs, and
not two parts of one program, is that each makes sense separately.
WIN-X is a general emulator for X Windows, and this version of GNU Emacs
has no modifications specific to use with WIN-X.  It could run with any
X Windows emulator (or, on other systems, with X Windows).

Introduction
************

   Welcome to Win-Emacs!

   Win-Emacs is a version of the popular GNU Emacs programming editor
that runs under Microsoft Windows.  Win-Emacs requires Windows 3.1
running on a machine with a 386 or better processor and at least 6
megabytes of memory.  9 megabytes of free hard-disk space is required
for a complete distribution.

   Win-Emacs also includes full 32-bit ports of the GNU versions of the
popular Unix utilities grep, diff, and patch.

   GNU Emacs is a powerful, customizable programming editor that is also
available on nearly every variety of Unix, on Vax VMS, and on most other
operating systems.  Win-Emacs is a complete implementation of GNU Emacs,
meaning that the features you may be used to in other versions of GNU
Emacs will be present in Win-Emacs.

   Win-Emacs is based on Lucid GNU Emacs 19.6 (now called XEmacs),
which is a version of GNU Emacs that provides extensive windowing and
GUI (graphical user interface) features and runs under Unix on the X
Window System.  Although there are other windowing versions of GNU
Emacs, Lucid Emacs is the most powerful and best-designed, and is the
only version supported by large software companies (Sun Microsystems
Inc., Amdahl, and others); this is why we chose to base Win-Emacs on it.

   This manual assumes that you have some knowledge of how to use some
version of Emacs (although not necessarily a windowing version).  If
you are unfamiliar with Emacs, choose the `Emacs Tutorial' option from
the `Help' menu for a quick introduction to editing with Emacs.

   This manual is available both as a printed document and on-line, by
choosing the `Info' option from the `Help' menu and selecting
`Win-Emacs'.  There is also extensive on-line reference documentation
describing Win-Emacs, E-Lisp (the dialect of the Lisp language that is
used to customize Win-Emacs), and various associated packages.

   If, after reading this manual, you have further questions or comments
about Win-Emacs, feel free to contact Pearl Software (*note Contacting
Pearl Software::.).

Getting Started
***************

   This chapter explains how to install Win-Emacs on your system and
get it up and running.

Installation
============

   * If you received Win-Emacs on floppies:

     Installation is accomplished through the `SETUP.EXE' program
     located on the disk `Win-Emacs 1' in the distribution.  Insert this
     disk in drive A and type `A:SETUP' from a DOS prompt; or from
     within Windows, select the `Run' command from the `File' menu in
     Program Manager and type `A:SETUP.EXE'.  Setup will start Windows
     automatically if it is not currently running, and will allow you to
     select the sections of Emacs you wish to install.  The "Core
     Program Files" must be installed in order for Emacs to work.  This
     includes the binaries, compiled Emacs-Lisp files, and files in the
     `etc' subdirectory.  "Emacs Info" refers to the online
     documentation files; you may choose not to install these files if
     you wish.

   * If you downloaded a demo version by FTP or off of a CD-ROM:

     You will need to unpack the files from whatever form they are in.
     If they are in a `.ZIP' file, this file should be unpacked using
     `PKUNZIP -d'. (The `-d' option is important - it creates the
     necessary subdirectories.) You need to use version 2.0 or greater
     of `PKUNZIP'.  If the files have already been unpacked, you simply
     need to copy them into the proper location (e.g. using `XCOPY'),
     making sure to preserve the subdirectory structure.  If there is
     not already a subdirectory `LOCK' off of the top-level directory,
     you must create it.

Configuring Your System for Win-Emacs
=====================================

Setting Up Your Path
--------------------

   If you plan on using the utilities `etags', `grep', `diff', or
`patch' from MS-DOS or from a DOS box inside of Windows, you need to
add the `etc' subdirectory (for example, `c:\winemacs\etc' if you
installed Win-Emacs in `c:\winemacs') to your PATH (usually specified
in your `AUTOEXEC.BAT' file).  Note that you do not have to do this if
you only use these utilities from inside Win-Emacs: it knows how to
find them regardless of your PATH.

   Your PATH cannot be longer than 128 characters; if this becomes a
problem, one trick is to use the MS-DOS `SUBST' command.  For example,
if `H:' does not refer to an existing drive, add a line like

     subst h: c:\winemacs\etc

   to your `AUTOEXEC.BAT' file, and then add `H:\' to your PATH.  This
same trick can be used multiple times (with different drive letters, of
course) to reduce the length of your PATH.  Note that you may have to
add a line like

     lastdrive=h

   to your `CONFIG.SYS' file.  See your MS-DOS manual for details.

Increasing Your Virtual Memory
------------------------------

   Win-Emacs uses a fair amount of memory in normal operation and does
not perform well in low-memory conditions.  We recommend that you have
at least 20 megabytes of virtual memory. (Note that this does *not*
mean that you actually need this much RAM in your system!  A normal
amount like 8 megabytes of RAM should do.)

   To increase the amount of virtual memory, go into Control Panel and
select the `386 Enhanced' icon; then click on the button labeled
`Virtual Memory'.

Specifying the Location of Startup Files
----------------------------------------

   You can specify the directory where Win-Emacs looks for startup
files by setting the environment variables `EMACSHOME' or `HOME'.  (If
neither is set, Win-Emacs looks in `C:\'.) For more info, *Note
Initialization Files::.

Running Win-Emacs
=================

   Once Win-Emacs has successfully been installed, you can run it in
any of the following ways:

  1. From File Manager, locate the file `WINEMACS.EXE' (this is in the
     `bin' subdirectory of the directory you installed Win-Emacs in).
     Double-click on it to run.

  2. From Program Manager, select `Run' from the File menu and type in
     the full pathname of `WINEMACS.EXE' (see option 1).

  3. In Program Manager, create a program item and give the full
     pathname of `WINEMACS.EXE' as the command line.  You may
     optionally specify a directory that will be current when Win-Emacs
     starts; this is the default directory when Win-Emacs searches for
     files.  If you do not specify a current directory, the Windows
     directory will be current.

Overview of Win-Emacs
*********************

Using the Keyboard
==================

   Emacs was originally designed for use on character-mode terminals,
which lacked menus and mice and often had no arrow or keypad keys;
thus, it is completely controllable from the main portion of the
keyboard.  However, you will probably find it easier to make use of the
keypad, mouse, and menus.

   For an introduction to how to control Emacs with the Keyboard, choose
the `Emacs Tutorial' option from the `Help' menu.

   The following keypad key combinations are defined:

   *Movement Keys:*

`Left', `Right'
     Move backward or forward by one character.

`Ctrl-Left', `Ctrl-Right'
     Move backward or forward by one word.

`Meta-Left', `Meta-Right'
     Move backward or forward by one balanced expression or word.

`Up', `Down'
     Move up or down by one line.

`Ctrl-Up', `Ctrl-Down'
     Move up or down by one block (the definition of this is
     mode-dependent).

`Meta-Up', `Meta-Down'
     Move backward or forward by one balanced group of parentheses.

`PageUp', `PageDn'
     Move up or down one page.

`Meta-PageUp', `Meta-PageDn'
     Scroll the other window up or down one page.

`Home', `End'
     Move to the beginning or end of the line.

`Ctrl-Home', `Ctrl-End'
     Move to the beginning or end of the buffer.

`Meta-Home', `Meta-End'
     Move to the beginning or end of the other window's buffer.

   *Text Deletion/Insertion Keys:*

`BackSpace', `Delete'
     Delete the character before or after (at) point.

`Meta-BackSpace', `Meta-Delete'
     Delete the word before or after point.

`Shift-Delete'
     Equivalent to the `Cut' menu item.

`Control-Insert'
     Equivalent to the `Copy' menu item.

`Shift-Insert'
     Equivalent to the `Paste' menu item.

`Control-Delete'
     Equivalent to the `Clear' menu item.

   *Other Keys:*

`Ctrl-Tab', `Ctrl-Shift-Tab'
     Switch to the next or previous window in this screen.

`Insert'
     Toggle between insert and overwrite mode.

Using the Mouse
===============

The Left Mouse Button
---------------------

   The left mouse button is used to set the insertion point, select
text to be operated on (e.g. cut or copied to the clipboard,
reformatted, etc.), and perform actions associated with a highlighted
block of text.  The gestures that can be performed using the mouse are
"clicking" (pressing and releasing the button without moving the mouse),
"double-clicking" and "triple-clicking" (rapidly clicking the button
twice or three times in succession without moving the mouse),
"dragging" (pressing the button, moving the mouse while the button is
held down, and then releasing the button), and "double-dragging" and
"triple-dragging" (like double-clicking and triple-clicking except that
a drag is performed before the final release of the mouse button).

   Clicking anywhere in the text normally sets the insertion point
before the character that was clicked on (or at the end of a line if
the click occurred beyond the end of a line), and a block cursor marks
the location of the insertion point.  However, clicking on a highlighted
block of text (e.g. a cross-reference in Info or a completion in the
completion buffer) performs the action associated with the text (e.g.
following the cross reference or selecting a completion).  In this
context, "highlighted" means that the block of text is momentarily
highlighted (typically by turning green) when the mouse passes over it.
This should not be confused with the less transient sort of highlighting
that occurs when you select a block of text by dragging the mouse over
it. (This is usually indicated by marking the text gray.)  Note that, if
you just want to set the insertion point in the middle of a highlighted
block of text, hold down the `Control' key when clicking; this
overrides any action that is associated with the text.

   Here is a list of common sorts of highlighted text that have actions
associated with them.

   * A cross-reference in Info.

   * A possible completion in the `*Completions*' buffer, when you hit
     `Tab' or `Space' in the minibuffer.

   * A file or directory in Dired.

   * A compilation error or searching match, when you use `M-x compile'
     or `M-x grep'.

   * A buffer in buff-menu (a listing of current buffers that is
     displayed using `C-x C-b').

   Dragging the mouse over a block of text selects the text, and
normally unselects any other text that may be selected.  However,
holding down the Shift key when clicking or dragging first causes the
old selected text (if any) and all text between the previous insertion
point and the current mouse location to become part of the new
selection.  This is called "Extending a Selection" and is commonly used
as a way of selecting text without having to drag the mouse.

   Double-clicking is a short-cut gesture that selects the word that
surrounds or abuts the cursor; similarly, triple-clicking selects a
line.  Double-dragging and triple-dragging select text a word at a time
or a line at a time.  These latter gestures are often forgotten about,
but can make selecting text much easier.

   If there is more than one window on a screen, pressing the mouse
button while over a modeline and then dragging causes the modeline to
get dragged, thereby resizing the windows.

The Middle Mouse Button
-----------------------

   On a three-button mouse, pressing the middle mouse button while some
text is selected causes the selected text to be copied and inserted at
the current mouse position.

   Pressing the middle mouse button on a highlighted block of text
normally causes the action associated with the text to be performed,
just as if the left mouse button were clicked. (This exists for
compatibility reasons.)

   If you have a two-button mouse, the same functionality as the middle
mouse button is available by holding down the `Meta' (i.e. `Alt') key
and pressing the right button.

The Right Mouse Button
----------------------

   The right mouse button normally brings up a popup menu at the current
mouse position.  The contents of the popup menu are dependent on the
mode of the current buffer and usually contain commonly used commands
for easy access.

   Holding down the `Meta' key while pressing the right mouse button is
equivalent to pressing the middle mouse button (see the previous
section for details).

Drag-and-Drop
-------------

   You can drag files from the File Manager and drop them onto a
Win-Emacs screen.  For each file dropped, a new screen will be created
that is visiting that file.

Remapping the Pointer
---------------------

   Win-Emacs doesn't actually think in terms of left, middle, and right
buttons, but in terms of "button1", "button2", and "button3".  By
default, button1 is the left button, button2 is the middle one, and so
on; this results in the behavior described above.  However, you can
change these associations using the `xmodmap.ini' file.  For example,
you could make button2 be the right button and button3 be the middle
one, and then pressing the middle button would bring up a pop-up menu
and pressing the right one would insert the selected text at the
current mouse position.  For details, *Note xmodmap.ini::.

Using the Menus
===============

   Win-Emacs has a menubar that behaves like any other Windows menubar.
It contains the most common editing commands for easy access.  The
contents of the menubar can vary from buffer to buffer, and will change
when you switch buffers; usually this variation consists of extra
buffer-specific commands in some modes (e.g. W3 menus when you are in
W3 mode).

   Keyboard traversal using Alt in combination with letter keys is
disabled because Alt is the same as Meta and is used for many keyboard
commands.  However, you can still traverse to the menu with the
keyboard by pressing and releasing the Alt key without any intervening
keystrokes.

   Win-Emacs also has popup menus that are accessible by pressing the
right mouse button (*note The Right Mouse Button::.).

   The menubar and popup menus are fully programmable.  For details,
see the documentation for the E-Lisp variable `current-menubar' and the
functions `popup-menu' and `popup-mode-menu'.  If you want to turn off
the menubar, use the E-Lisp command `(set-menubar nil)'.

Dialog Boxes
============

   Win-Emacs currently has dialog boxes for changing the font of the
screen and controlling printing.  These are accessible from the `Set
Font...' option on the `Display' menu and the `Print...' and `Print
Setup...' options on the `File' menu.

Creating and Managing Multiple Screens
======================================

   Multiple windows ("screens" in Win-Emacs terminology) can be created
by typing `C-x 5' or selecting `New Screen' from the `File' menu, and
can be resized, moved around, and iconified independently from all
other screens.  You can also create a new screen that is visiting a
particular file by choosing `Open File in New Screen' from the `File'
menu.  Closing a screen using the system menu in the upper-left corner
of the screen will delete the screen if there is more than one, and
quit Win-Emacs if there is only one screen.  You can also use the
`Delete Screen' item on the `File' menu if there is more than one
screen.

More About Win-Emacs
********************

Printing
========

   Full WYSIWYG ("what you see is what you get") printing support and
integration with Print Manager is provided.  Standard Print and Print
Setup dialog boxes are provided to facilitate printer control; these are
available from the `Print...' and `Print Setup...' options on the
`File' menu or from the commands `M-x lpr-buffer' and `M-x lpr-region'.

Notes About Printing
--------------------

   You may notice that lines of printed output are spaced somewhat
differently than lines on the Emacs display.  Lines on the Emacs display
are always spaced at a constant distance, so that if one line contains
characters in a large font, all lines in the buffer will be spaced at a
large distance even if they contain only characters in a small font.
Lines of printed output are spaced variably according to the sizes of
fonts that appear in those lines.

   Begin-glyph and end-glyph objects (graphic symbols which can be
attached to a range of Emacs text - see the Emacs `NEWS' file for
details) are not printed.  We may fix this at a later time.

   Your printed output will best match the screen display if you use
TrueType fonts.

Printing Variables
------------------

   Several Emacs variables control the appearance of printed output.

   The variables `print-margin-left', `print-margin-right',
`print-margin-top', and `print-margin-bottom' hold floating-point
numbers representing the margins for printing.  Each has a default
value of 0.0.  The variable `print-margin-units' holds either the
symbol `cm' or `inch' representing the units in which the margin values
are to be interpreted.

   The variable `print-wrap' holds a Boolean value (`t' or `nil') and
controls how lines which are too wide for the printed page are printed.
If `print-wrap' is `t', a line which is too wide will wrap around to
the next printed line; if `nil', then a line which is too wide will be
truncated at the right margin.  The `print-wrap' variable affects
printed output just as the `truncate-lines' variable affects the
display of Emacs buffers on the screen.

Printing Functions
------------------

   This section is only of interest if you are writing Emacs-Lisp code.

 - Command: win-print-region START END &optional BUFFER SCREEN JOBNAME
     This function prints the contents of a region of a buffer after
     displaying the Print dialog box.  The Lisp code for the Print
     Buffer menu item calls this function.

     Arguments START and END specify the region to print.  BUFFER is
     the buffer.  SCREEN is the screen which is used for mapping faces
     to fonts. (Because each screen has its own face-to-font mapping, a
     buffer may appear different in two different screens.) JOBNAME is
     the print job name which will appear in Print Manager (max 31
     characters).

     BUFFER, SCREEN, and JOBNAME are optional, and default to the
     current buffer, the selected screen, and a name constructed from
     the buffer name, respectively.

     If there is a selected region, the `Selection' choice in the dialog
     box will be enabled and chosen by default; otherwise, it will be
     disabled.  When `Selection' is the default and the user chooses
     `All', the entire visible portion of the buffer will be printed.

     Returns `t' if the document was successfully printed, `nil'
     otherwise (i.e. the user canceled the operation).

 - Command: win-print-setup
     This function displays the Print Setup dialog box.  It takes no
     arguments.

Syntax Highlighting
===================

   "Syntax highlighting" refers to decorations placed on parts of code
to make it easier to read.  For example, comments might be displayed in
red, strings in green, and function names in function definitions in
blue.  Syntax highlighting makes it so much easier to read code that,
once you get used to it, you may find it strange to read unadorned code.

   Syntax highlighting is accomplished in Win-Emacs using the
"font-lock" package.  You can switch into font-lock mode using the
command `M-x font-lock-mode'.  This causes the buffer to be fontified;
afterwards, any new text you enter will be fontified on-the-fly.  If at
any point you want to refresh the fontification in a buffer, use the
commands `M-x font-lock-fontify-buffer' or `M-x
font-lock-fontify-region'.

   The default decorations for font-lock are done using italicized,
boldfaced, and underlined fonts.  If you are on a color display, you
will probably find it prettier to use colors instead.  Here is some
E-Lisp code you can add to your `emacs.ini' file to do this:

     (require 'font-lock)
     (set-face-foreground 'font-lock-function-name-face "blue")
     (set-face-foreground 'font-lock-comment-face "red")
     (set-face-foreground 'font-lock-string-face "forest green")
     (set-face-underline-p 'font-lock-string-face nil)
     (make-face-unitalic 'font-lock-string-face)
     (make-face-unitalic 'font-lock-function-name-face)
     (make-face-unitalic 'font-lock-comment-face)
     (copy-face 'font-lock-function-name-face 'font-lock-keyword-face)
     (copy-face 'font-lock-string-face 'font-lock-doc-string-face)
     (copy-face 'font-lock-string-face 'font-lock-type-face)

   Experiment with the colors and fonts if you like (for more details,
*note Customization::.).

   Once you get used to font-lock, you will probably want it to happen
automatically when you visit a file containing code.  Here is some code
for your `emacs.ini' file to do so:

     (defun turn-on-font-lock ()
       (font-lock-mode 1))
     (add-hook 'emacs-lisp-mode-hook	'turn-on-font-lock)
     (add-hook 'lisp-mode-hook	'turn-on-font-lock)
     (add-hook 'c-mode-hook		'turn-on-font-lock)
     (add-hook 'c++-mode-hook	'turn-on-font-lock)
     (add-hook 'perl-mode-hook	'turn-on-font-lock)
     (add-hook 'tex-mode-hook	'turn-on-font-lock)
     (add-hook 'texinfo-mode-hook	'turn-on-font-lock)

   Both of these code fragments are available in the sample `emacs.ini'
file in the `etc' subdirectory of the distribution.

Subprocesses
============

   You can run another program from Win-Emacs and optionally have its
output placed in a buffer or otherwise processed.  This allows you to
perform any action you want on the text and build up very powerful
packages. (Note! Subprocess support does not currently work under
Windows NT.)

   Under Windows, there are two kinds of programs: native Windows
applications and MS-DOS applications running in a DOS box.  Native
Windows applications are started from Win-Emacs using `win-exec' and
execute "asynchronously", meaning they run concurrently with Win-Emacs
(just as if you had started the application from Program Manager).  DOS
applications are run from Win-Emacs using `shell-command' and friends,
and execute "synchronously", meaning that Win-Emacs waits until the
application finishes before proceeding.  The reason that Win-Emacs
waits is so that it can retrieve the output from DOS command.

   It is not currently possible to run a DOS application asynchronously
and have Win-Emacs pass input to it or retrieve output from it while it
is running.  However, if you don't care about the output (or arrange to
retrieve it yourself, rather than have Win-Emacs do it for you), you
can go ahead and start a DOS application asynchronously using
`win-exec', just as if it were a Windows application.  (If you do this,
you might want to create a PIF file to get more control over the
application.  See the `Microsoft Windows User's Guide' for more
information.)

Running a DOS Process
---------------------

   To run a DOS process and have its output inserted in a buffer, use
`M-!' (or equivalently `M-x shell-command').  For example, if you type
`M-! mem RET' then you will get a buffer containing something like this:

     Memory Type        Total  =   Used  +   Free
     ----------------  -------   -------   -------
     Conventional         640K      210K      430K
     Upper                 91K       91K        0K
     Reserved             384K      384K        0K
     Extended (XMS)    15,269K   14,245K    1,024K
     ----------------  -------   -------   -------
     Total memory      16,384K   14,930K    1,454K
     
     Total under 1 MB     731K      301K      430K
     
     Total Expanded (EMS)                1,024K (1,048,576 bytes)
     Free Expanded (EMS)                 1,024K (1,048,576 bytes)
     
     Largest executable program size       430K (440,528 bytes)
     Largest free upper memory block         0K       (0 bytes)
     MS-DOS is resident in the high memory area.

   This is the output from the DOS `mem' program, which reports
information about DOS memory usage.

   You can also use a DOS application as a "filter", meaning that some
text is given as input to the program and its output replaces the text.
To filter some text through a DOS application, select the text and
then type `M-|' (or equivalently, `M-x shell-command-on-region').

   For example, say you wanted to sort some lines of text.  One way to
do it is to select the text and then type `M-| sort RET'.  This passes
the text through the DOS `sort' program, which sorts its input and
outputs the result.

   If you run a DOS subprocess and it hangs, Emacs normally will wait
forever, expecting it to finish.  You can break out of this by pressing
`C-g'.

compile/grep/diff
-----------------

   Built on top of Emacs' subprocess support are packages that provide
interfaces to compilers and to the standard Unix utilities `grep' (for
searching for text in one or multiple files) and `diff' (for detecting
differences between two text files).  Because `grep' and `diff' do not
come as part of DOS, Win-Emacs provides 32-bit ports of the GNU
versions of them. (The GNU utilities are compatible with the original
Unix ones but generally are faster, more powerful, and more robust.)
Because these utilities run in 32-bit mode, you will not encounter
memory limitations that might otherwise, for example, make it
impossible to run `diff' to compare large text files.

   To run the compiler, use the command `M-x compile'.  You will be
prompted for a command line to run the compiler (e.g. `make'), and then
the compiler will be run as a subprocess.  When it finishes, any errors
that were generated will be parsed and placed in a special compilation
output buffer.  If you click on any error in the buffer, or hit `C-x `'
to access the next error in sequence, Win-Emacs visits the file
containing the error and jumps to the line in that file where the error
occurred.  This allows you to very quickly locate and correct errors
and then recompile.

   `M-x grep' works very similarly to `M-x compile'.  You are prompted
for a command line to run `grep', and all matches that are found are
displayed in a buffer.  Clicking on a match or using `C-x `' brings you
to the file and location within the file where the match occurred.

   `M-x diff' prompts you for the filenames to compare, and then
displays the resulting differences in a special buffer, one difference
at a time.  There are keyboard commands to display the next or previous
difference, jump to a numbered difference, etc.  For details, type `C-h
m' when in the diff buffer.

Running a Windows Process
-------------------------

   You can start a Windows application using the E-Lisp function
`win-exec'.

 - Function: win-exec PROGRAM SHOW-STATE &optional ARGS
     This function runs the Windows program PROGRAM and doesn't wait
     for it to finish.  Second argument SHOW-STATE specifies how the
     program's window will be shown, and should be one of the following
     symbols:

    `win-show-hide'
          Hide the window, don't change focus.

    `win-show-min'
    `win-show-min-focus'
    `win-show-min-focus-next'
          Minimize the window; don't change the focus, focus on the
          window, and focus on the next top-level window, respectively.

    `win-show-max-focus'
          Maximize the window and focus on it.

    `win-show-normal'
    `win-show-normal-focus'
          Show the window in its normal state (not maximized or
          minimized); don't change the focus or focus on the window,
          respectively.

    `win-show-current'
    `win-show-current-focus'
          If the window was hidden, set it to its previously shown
          state; otherwise don't change the state.  Don't change the
          focus or focus on the window, respectively.

     Some of the above values only make sense if an instance of the
     program is already running.  Note that the display-state specified
     here is only a suggestion to the program, which is free to ignore
     or reinterpret it.

     Any remaining arguments are the parameters passed to the program.

Controlling Subprocesses
------------------------

   DOS processes use the PIF file `spr.pif' in the `etc' subdirectory.
By modifying this file using PIF Editor, you can control the way a DOS
process is invoked.

   The current directory of the DOS process is the default directory of
the buffer that was current when the process was started.  Normally
this is the directory that the buffer's file is located in, but this
can be changed with the `M-x cd' command.

   The following variables control how a DOS process is run.

 - Variable: exec-directory
     This variable specifies the directory that holds the programs that
     come with Win-Emacs, such as `grep' and `diff'.  This is the full
     pathname of the `etc' subdirectory.

 - Variable: exec-path
     This variable contains a list of directories to search programs to
     run in subprocesses.  Each element is a string (directory name) or
     `nil' (try default directory).  In Win-Emacs, this is initialized
     from the `PATH' environment variable and has the value of
     EXEC-DIRECTORY prepended. (This way, incompatible applications
     sitting elsewhere in the search path with names like `grep.exe' or
     `diff.exe' will not mess up `M-x grep' or `M-x diff'.)

 - Variable: msdos-shells
     This variable holds a list of DOS shell programs that use the
     `command.com'-style method of specifying a command to be executed
     (i.e. `/c' followed by a command with backslashes as directory
     separators).  By default, this lists `command.com', `4dos.com',
     and `ndos.com'.  Do *not* add shells such as the MKS `sh.exe' to
     this list; it uses Unix-style specifications.

 - Variable: win-dos-process-show-state
     This variable specifies the show state for invoked DOS processes.
     This is the second parameter in the call to the Windows function
     `WinExec()'.  The possible values are the same as those for the
     SHOW-STATE argument to the E-Lisp `win-exec' function (*note
     Running a Windows Process::.).

Network Connections
===================

   Win-Emacs can connect to services provided by other machines on the
local network or the global Internet.  Win-Emacs uses Windows Sockets, a
standard protocol which allows Windows applications to talk to networks.
If you have `winsock.dll' (the library which implements Windows
Sockets) installed on your computer, you can use Win-Emacs to access
network services.

   Many packages are available for Win-Emacs that allow you to read
network news, access remote mail, etc.  The Emacs Lisp distribution
included with Win-Emacs includes GNUS, a package that allows you to
read network news using NNTP (Network News Transfer Protocol), and W3,
a package that lets you browse the World Wide Web.  You can find more
Emacs Lisp network packages on the Internet (*note Other Packages::.).

   If you are interested in writing Emacs-Lisp code to access the
network, see the documentation for the E-Lisp function
`open-network-stream', which is used to open a network connection.
Like other versions of GNU Emacs, Win-Emacs uses process objects to
represent open network connections.  Win-Emacs currently does not
support asynchronous subprocesses, so in fact every process object under
Win-Emacs represents a network connection, and `open-network-stream' is
the only way to create process objects.  See the Emacs Lisp
documentation for details about functions which operate on process
objects.

   If a network error occurs, Win-Emacs will signal a `winsock-error'
with an accompanying error message.

DDE Support
===========

   This section is only of interest if you are writing Emacs-Lisp code.

   Using Emacs Lisp, you can use DDE (Dynamic Data Exchange) to exchange
data between Win-Emacs and other Windows applications.  Emacs can
exchange data in text format only.

Intro to DDE
------------

   The Emacs Lisp data type handle represents open DDE connections and
asynchronous DDE transactions.  The functions `dde-connect',
`dde-execute' and `dde-request', below, return handle objects.  The
only operation you can perform on handles is to compare two handles
using `equal'. (Internally, a handle holds a 32-bit integer
representing a Windows handle.)

   Please note that all service, topic, and item names in DDE are
case-insensitive.

DDE Client
----------

   The following Emacs Lisp functions allow Emacs to act as a DDE
client.

 - Function: dde-connect SERVICE TOPIC
     This function initiates a conversation with a DDE server.  The DDE
     server application must already be running.  SERVICE is a string
     naming the DDE server to connect to; typically, this is just the
     name of the DDE server application.  TOPIC is a string naming the
     topic for the DDE conversation.  Most DDE servers support the
     `System' topic.  Consult the documentation for your DDE server
     application to find out what topics it supports.

     This functions returns a handle object representing the DDE
     conversation.  You can pass this object to other DDE functions
     such as `dde-execute' and `dde-request'.

 - Function: dde-execute HANDLE COMMAND TIMEOUT
     This function sends a command to a DDE server.  HANDLE is a handle
     which was returned by a previous call to `dde-connect'.  COMMAND
     is a command string to be sent to the DDE server.  For a
     synchronous transaction, TIMEOUT is the maximum time, in
     milliseconds, to wait for a reply from the server.  For an
     asynchronous transaction, TIMEOUT is 0.

     For a synchronous transaction, this function returns `t' if the
     command execution succeeds, and signals a `dde-error' if the
     command execution fails or times out.  For an asynchronous
     transaction, this function immediately returns a handle
     representing the transaction; when the server has executed the
     command, Emacs calls the function contained in the
     `dde-acknowledge' variable; see details below.

 - Function: dde-request HANDLE ITEM TIMEOUT
     This function requests data from a DDE server.  HANDLE is a handle
     which was returned by a previous call to `dde-connect'.  ITEM is a
     string naming the item to request from the server.  For a
     synchronous transaction, TIMEOUT is the maximum time, in
     milliseconds, to wait for a reply from the server.  For an
     asynchronous transaction, TIMEOUT is 0.

     For a synchronous transaction, this function returns a string
     containing the requested data if the command execution succeeds,
     and signals a `dde-error' if the request fails or times out.  For
     an asynchronous transaction, this function immediately returns a
     handle representing the transaction; when the server replies with
     the data, Emacs calls the function contained in the
     DDE-ACKNOWLEDGE variable; see details below.

 - Variable: dde-acknowledge
     When a server completes an asynchronous request made with
     `dde-execute' or `dde-request', Emacs calls the function contained
     in the `dde-acknowledge' variable.  This function is called with 4
     arguments: HANDLE, TOPIC, ITEM, and DATA.  HANDLE is a handle
     returned by `dde-execute' or `dde-request' and indicates the
     transaction which is being answered.  TOPIC is the topic name of
     the conversation in which the transaction was performed.  ITEM is
     the item name passed to `dde-request', or is `nil' if the request
     was made with `dde-execute'.  For a command execution, DATA is `t'
     if the command execution succeeded, or `nil' if it failed.  For a
     data request, DATA is a string containing the requested data, or
     `nil' if the request failed.

     If `dde-acknowledge' is `nil', Emacs simply ignores any
     transaction acknowledgements.  The default value for
     `dde-acknowledge' is `nil'.

 - Function: dde-disconnect HANDLE
     This function terminates a DDE connection.  HANDLE is a handle
     which was returned by `dde-connect'.

DDE Server
----------

   Windows applications can initiate conversations with Emacs as a DDE
server, and can ask Emacs to execute Emacs Lisp code.  You can use Emacs
Lisp to extend Emacs' behavior as a DDE server.

   The default behavior of Emacs as a DDE server is simple.  A Windows
application can initiate a DDE conversation with Emacs using the service
name `Emacs' and the topic name `System'.  An application can send a
DDE command of the form `[lispCode]' to ask Emacs to execute Emacs Lisp
code.  For example, the command `[(beep)]' will cause Emacs to beep.

   By default, Emacs also responds to several standard DDE requests
under the `System' topic as follows:

`formats'
     Sends a list of data formats Emacs supports: only `Text'.

`help'
     Sends text explaining how to execute Emacs Lisp commands through
     DDE.

`topics'
     Sends a list of DDE topics Emacs supports; initially, only
     `System'.

   The Lisp code in `ddeservr.el' implements the default DDE server
behavior described above.  You can change this code to support different
kinds of DDE requests.  For example, you could add code which would
allow client applications to retrieve text from Emacs buffers or to
inquire about the values of Emacs Lisp variables.

 - Variable: dde-topics
     This variable contains a list of strings representing topic names
     on which Emacs will accept DDE connections.  Initially,
     `dde-topics' contains only `System'.  You can add strings to
     `dde-topics' to allow Emacs to accept connections on other topics.
     If `dde-topics' is `t', Emacs will accept conversations on any
     topic.

 - Variable: dde-server-execute
     When a DDE command execution request arrives, Emacs calls the
     function contained in this variable to process the request.  The
     function receives 3 arguments: CONV, TOPIC and ITEM.  CONV is a
     handle representing the conversation in which the request was made
     (you will probably want to ignore this value except in exceptional
     circumstances in which you want to see which requests came from a
     single conversation).  TOPIC is a string representing the
     conversation topic, and ITEM is a string representing the command
     to execute.  The function should return a Boolean value
     representing whether the command execution was succesful.  If any
     error occurs during the execution of the function in
     `dde-server-execute', a command execution failure will immediately
     be reported to the DDE client.

     The code in `ddeservr.el' defines `dde-server-execute' to contain
     a function which processes DDE commands of the form `[lispCode]'
     as described above.

 - Variable: dde-server-request
     When a DDE data request arrives, Emacs calls the function
     contained in this variable to process the request.  The function
     receives 3 arguments: CONV, TOPIC and ITEM.  CONV is a handle
     representing the conversation in which the request was made.
     TOPIC is a string representing the conversation topic, and ITEM is
     a string representing the requested data item.  The function
     should return a string containing the data to return to the client
     application, or `nil' to deny the request.

     The code in `ddeservr.el' defines `dde-server-request' to process
     the standard DDE system requests as described above.

DDE Example
-----------

   The Lisp file `ddeexamp.el' in the `samples' subdirectory contains
some examples of Emacs Lisp code that uses DDE.

Editing Binary Files
====================

Introduction to Text and Binary Files
-------------------------------------

   In a standard MS-DOS text file, the end of a line is signalled with
two characters, `CR' (ASCII 13) and `LF' (ASCII 10).  (Unix text files,
on the other hand, signal the end of a line with just a `LF'.) In
addition, any `^Z' character encountered is not to be considered part
of the text, but rather marks the end of the file, and any text after
it is to be ignored.  To facilitate editing both MS-DOS and Unix format
text files, Win-Emacs normally treats both a `CR'/`LF' combination and
a sole `LF' as marking the end of a line when reading in a text file,
and ignores a `^Z' character and any characters after it.  When saving
the file out to disk, a `CR'/`LF' is written at the end of each line
and a `^Z' is written at the end of the file. (This means, for example,
that you can convert a Unix-format text file into an MS-DOS-format text
file simply by reading it into Win-Emacs and writing it out again.)

   Sometimes these translations are not desirable; for example,
performing the translations on a `.EXE' file is likely to corrupt the
file.  When editing such a file, Win-Emacs does no translation on
either input or output.

   The "file type" of a file determines what sort of translation (text
or binary) is to be performed when reading in and writing out a file.
When editing an existing file in Win-Emacs, Win-Emacs normally
determines the file type of the file by looking at its extension (for
example, `.C' or `.EXE').  If it is not sure, it treats the file as
text, since this is the most likely case.  When writing out a file,
Win-Emacs looks at the `file-type' variable for the file's buffer.
This is normally set according to the file's extension when the buffer
is created, so everything stays in sync.

   For easy reference, the file type of a buffer is displayed in the
modeline, as either a `T' or `B' preceding the buffer's major mode.
For example:

     --**-Emacs: lispref.txi          (T:Texinfo)----42%---------------

   indicates that the file `lispref.txi' is being edited in Texinfo
major mode and the file type is Text.

Controlling the File Type
-------------------------

   You can explicitly set the file type of a buffer using the command
`M-x set-file-type'.  This accepts the strings `text' and `binary'.
Note that `M-x set-file-type' affects the way that the file will be
written out to disk, but not how it was read in, since this has already
occurred by the time `M-x set-file-type' can be used.

   To explicitly specify the translations to be performed when a file
is read in, use the commands `M-x find-file-text' and `M-x
find-file-binary'. These commands cause Win-Emacs to treat the file
(and set the `file-type' variable of the file's buffer) accordingly,
regardless of the file's extension.  If you just began editing a file
and notice that Win-Emacs guessed the wrong file type, you probably
want to type `C-x k' to kill the buffer, and then use one of the above
commands to edit the file again.

   It was mentioned above that, if Win-Emacs cannot determine the file
type of a file from its name, it assumes the file is text.  This can be
changed using the command `M-x set-default-file-type'.

Lisp-Level File Type Information
--------------------------------

   This section is only of interest if you are writing Emacs-Lisp code.

 - User Option: file-type
     This variable holds the file type for a buffer: non-`nil' for text,
     `nil' for binary.  It automatically becomes buffer-local when it is
     set it any fashion.

 - Command: set-file-type TYPE &optional BUFFER
     This function sets the value of `file-type' for BUFFER, which
     defaults to the current buffer.  When called interactively, it
     accepts the strings `text' and `binary'.  When called from Lisp, it
     also accepts the symbols `text' and `binary' as well as `t' and
     `nil'.

 - Command: set-default-file-type TYPE
     This function sets the default value of `file-type'.  Its argument
     is as in `set-file-type'.  The initial default value is `t', for
     text.

   When a file is loaded into a buffer, Win-Emacs normally sets the
buffer's file type according to the name of the file (in most cases,
specifically by looking at the file's extension) and performs
translations accordingly as the file is read in.  This can be overridden
using the commands `find-file-binary' and `find-file-text', described
in the previous section.

 - Variable: auto-compute-file-type-p
     This variable, which defaults to `t', determines whether the
     buffer's file type is set according to the name of the file. (If
     set to `nil', of course, the value of `default-file-type' will be
     used.)

 - Variable: file-name-file-type-alist
     This variable determines how a file type is obtained from a file
     name.  Its format is an alist associating regular expressions with
     file type values (`nil' or `t').  The alist is scanned and the
     first

     `file-name-file-type-alist' initially looks something like this:

          (defvar file-name-file-type-alist
            '(
              ("\\.elc$" . nil)  ; *.elc binary
              ("\\.obj$" . nil)  ; *.obj binary
              ("\\.exe$" . nil)  ; etc
              ("\\.com$" . nil)
              ("\\.lib$" . nil)
              ("/config.sys$" . nil); config.sys text
              ("\\.sys$" . nil)  ; *.sys binary
              ("\\.chk$" . nil)  ; *.chk binary ;; chkdsk.exe dumps this.
              ("\\.zip$" . nil)
              ; the rest are Windows files
              ("\\.dll$" . nil)
              ("\\.bmp$" . nil)
              ("\\.ico$" . nil)
              ("\\.res$" . nil)
              ("\\.pif$" . nil)
              ("\\.sym$" . nil)
              ("\\.scr$" . nil)
              ("\\.fon$" . nil)
              ("\\.fot$" . nil)
              ("\\.ttf$" . nil)
              ))

 - Function: find-file-name-from-file-type FILENAME
     This function looks up FILENAME in `file-name-file-type-alist' and
     returns the file type found (either `t' or `nil').  If FILENAME
     could not be matched, the default value of `file-type' is returned.

 - Function: define-file-name-file-type EXPR TYPE
     This function adds a new expression to the alist
     `file-name-file-type-alist'.  From now on, any file name matching
     regular expression EXPR will be considered to have file type TYPE,
     which should be `t' or `nil'.

Editing Files in Hex Mode
=========================

   To edit a file in hex-dump mode (called "hexl-mode" in Emacs), use
the command `M-x hexl-find-file'.

MS-DOS Filenames
================

   Under MS-DOS, filenames are composed of two parts, a base of 1 to 8
characters and an extension of 0 to 3 characters, with a period used to
separate the two parts. (More characters can be specified in the base
and extension, but they will be ignored.) Filenames are not
case-sensitive and are subject to many limitations on valid characters
(for example, a colon may not appear anywhere in a filename; a period
may only occur as the separator between the base and the exponent,
except in the special files `.' and `..'; etc.).

   Win-Emacs automatically converts all filenames to lowercase,
truncates their names to follow MS-DOS constraints, and checks for
invalid characters in a filename.  Drive specifications at the
beginning of a filename are recognized and accepted, and drive
specifications are handled correctly in such functions as
`file-name-absolute-p'.  The function `expand-file-name', which
converts a filename to its absolute representation, automatically
inserts the proper drive specification as necessary.  In addition,
slashes and backslashes are both accepted as directory separator
characters; backslashes are internally converted to slashes, to be
consistent with Unix.

   MS-DOS filename limitations make it infeasible to duplicate the
behavior of Emacs under Unix, where backup filenames are formed by
appending a `~' (or a `~' and a number, for numbered backups) and
auto-save filenames are formed by appending and pre-pending a `#'.
Instead, Win-Emacs forms backup filenames by appending a `~' to the
extension if it is fewer than 3 characters in length, and otherwise by
replacing the last character in the extension with a `~'.  Numbered
backups are disallowed entirely.  Auto-save filenames are formed by
pre-pending a `#' to the base (removing the last character of the base
if necessary) and appending a `#' to the extension just like `~' is
added for backup files.

Low-Level PC Functions
======================

Generating 8086 Software Interrupts
-----------------------------------

   8086 software interrupts can be generated using the function
`int86'.  (Please note that this function bypasses the protection
normally provided in E-Lisp, and can easily cause Win-Emacs, or Windows
itself, to crash.) Registers are passed in and returned in a special
"register" type (actually a vector of all the register values).  The
function `make-register' creates a new instance of register type;
`set-register-value' sets a particular register in such an instance;
and `register-value' returns the value of a register in such an
instance.  The `register' argument to these latter two functions is a
symbol specifying the register to be set or whose value is to be
retrieved, and can be one of the standard 8086 registers `ax', `bx',
`cx', `dx', `si', `di', `flags', `al', `ah', `bl', `bh', `cl', `ch',
`dl', `dh', or `cflag' for the carry flag.

   As an example, the following C code to determine the
currently-selected drive:

     int
     GetDisk ()
     {
         union REGS regs;
         regs.h.ah = 0x19;     /* 25 */
         int86 (0x21 /* 33 */, &regs, &regs);
         return regs.h.al;
     }

   may be written in Win-Emacs as follows:

     (defun get-disk ()
       (let ((regs (make-register)))
         (set-register-value regs 'ah 25)    ; 0x19
         (int86 33 regs)                     ; 0x21
         (register-value regs 'al)))

Accessing Linear Memory Directly
--------------------------------

   The E-Lisp functions `win-peek-linear-memory' and
`win-poke-linear-memory' can be used to directly access and change any
location in the linear memory of the current virtual machine.  Only use
these functions when absolutely necessary.

Other Packages
**************

   Many other interesting packages come with Win-Emacs, and a huge
number of other ones are available by FTP at

     archive.cis.ohio-state.edu:/pub/gnu/emacs/elisp-archive

   Here is a partial list of the packages included with Win-Emacs and
the commands or variables to access them.  If a filename is listed (e.g.
`autoinsert'), it means you must use `M-x load-library' to load the
file before accessing the package.  Otherwise, it will be loaded
automatically when you first use the associated command.

   Note that many of the packages below have auxiliary commands and
variables that control more precisely how to package behaves.  These
commands and variables usually have names related to the package's
name, and you can find them out using `M-x apropos' once the package is
loaded.

`M-x change-log-mode'
`M-x add-change-log-entry'
     Conveniently maintain a log of changes to a product.

`M-x apropos'
`M-x super-apropos'
     List all the symbols (i.e. commands, variables, etc.) that match a
     specified regular expression.  `M-x super-apropos' also looks
     through the documentation strings for the symbols.

`M-x array-mode' in `array'
     Edit a two-dimensional array of strings in a buffer.

variable `auto-insert-alist' in `autoinsert'
     Automatically insert text into a file when it's created.  The text
     inserted depends on the extension of the file, similarly to how
     the correct mode is determined for a file using AUTO-MODE-ALIST.

variable `big-menubar' in `big-menubar'
     An alternative menubar that contains many more entries than the
     standard one.  Loading this file automatically makes the big
     menubar current.

`blink-paren' package
     Loading this package causes the associated parenthesis (brace,
     bracket, etc.) to blink when the cursor is sitting on the matching
     one.

`C-x C-b' or `M-x buffer-menu'
     Display a list of buffers.  Allows you to manipulate them singly
     or in groups.

`M-x calendar'
`M-x diary'
`M-x holidays'
`M-x phases-of-moon'
`M-x sunrise-sunset'
etc. (`calendar' package)
     The `calendar' package consists of functions that display a
     three-month calendar, manage diary entries and appointments, list
     the holidays and phases of the moon around the current date,
     compute the sunrise and sunset times for a specified latitude and
     longitude, and do many other related things.  See the on-line
     documentation for details.

`M-x list-command-history'
`M-p' and `M-n' while in the minibuffer.
`C-x ESC' or `M-x repeat-complex-command'
`M-x repeat-matching-complex-command'
     List recent minibuffer commands.  You can edit and redo any
     particular command.  You can also scroll through recent minibuffer
     commands by using `M-p' and `M-n' while in the minibuffer, or use
     `C-x ESC' or `M-x repeat-matching-complex-command' to repeat the
     most recent or a specified minibuffer command.

`M-x compare-windows'
     Compare the text in the current window with the next window.

`M-x compile'
     Run a compiler.  For more information, *Note compile/grep/diff::.

`completer' package
     Loading this package causes a smarter completion mechanism for
     files and symbols to be installed.  For example, `M-x l-c-h' will
     automatically be converted to `M-x list-command-history'.

`crypt' package
     Loading this package causes encrypted and compressed files to be
     recognized and automatically encoded/decoded when you visit and
     save the file.

`M-/' or `M-x dabbrev-expand'
     Dynamically expand a prefix by looking for preceding words in the
     text (or following words, if no preceding words are found) that
     contain this word as a prefix.

`C-x d' or `M-x dired'
     "Edit" a specified directory - i.e. delete, rename, print, etc.
     some files in it.  This is also invoked when you use `C-x C-f' or
     `M-x find-file' and enter a directory name.

`M-x edebug-defun' in `edebug'
     `edebug' is a source-level debugging package for Emacs-Lisp code.
     `M-x edebug-defun' places a breakpoint at the beginning of the
     function before point and lets you trace through the function.
     See the on-line documentation for details.

`M-x emerge-files' in `emerge'
`M-x emerge-files-with-ancestor' in `emerge'
`M-x emerge-buffers' in `emerge'
`M-x emerge-buffers-with-ancestor' in `emerge'
     Merge two files or buffers together, with or without a common
     ancestor.

`M-x evi'
     Make Emacs emulate the popular VI editor under Unix.

`M-.' or `M-x find-tag'
`M-,' or `M-x tags-loop-continue'
     Visit the file where a specified symbol (function, global variable,
     etc.) is defined and jump to its definition.  Uses a `TAGS' file
     that is generated by the auxiliary program `etags'.  `M-.' finds
     the first occurrence and `M-,' loops through each other
     occurrence.  See the on-line documentation for details.

`M-x font-lock-mode'
     Dynamically add syntax highlighting to your code.  See *Note
     Syntax Highlighting:: for details.

`M-x hexl-find-file'
     Edit a file in hex-dump mode.

`M-x info'
     Enter the on-line documentation browser.  Also available as the
     `Info' item on the `Help' menu.

`M-x list-options'
`M-x edit-options'
     Display or edit a list of user-settable options.

`M-x edit-picture'
     Edit your text as a picture instead of as normal text.

`saveconf' package
     Automatically save and restore the context (i.e. the window
     configuration and the files that were being visited in them) when
     Emacs exits and starts up again.  See the sample `emacs.ini' file
     to find out how to use this.

`session' package
     Loading this file in your `emacs.ini' file causes the last file
     you visited to be reloaded at start-up.  This is a simpler version
     of the `saveconf' package.

`M-x display-time'
     Display the current time in the modeline.

   Win-Emacs also includes some games that you can play and other
diversions for when you are tired of working.

`M-x blackbox' in `blackbox'
     "Blackbox" game.  For details, see the documentation for this
     function.

`M-x conx'
`M-x conx-buffer'
`M-x conx-region'
     Creatively mangle your text.  Use `M-x conx-buffer' or `M-x
     conx-region' to scarf some words, and then `M-x conx' to generate
     the mangled text.

`M-x dissociated-press'
     Creatively rearrange your text.  Similar to `M-x conx'.

`M-x doctor'
     Let Emacs psychoanalyze you.

`M-x flame' in `flame'
     Generate random flames.

`M-x psychoanalyze-flamer' in `flame'
     Let Emacs psychoanalyze the flame generator.

`M-x gomoku' in `gomoku'
     Play Gomoku (similar to Go) with Emacs.  For details, see the
     documentation for this function.

`M-x hanoi'
     Demonstration of the famous "Towers of Hanoi" problem.

`M-x life' in `life'
     John Conway's mathematical game of Life.

`M-x spook' in `spook'
     Add random national-security-sensitive words to your text.

`M-x studlify-word' in `studly'
`M-x studlify-region' in `studly'
`M-x studlify-buffer' in `studly'
     Add Studly capitalization to a word, region, or buffer.

`M-x yow'
     Return a Zippy quotation.

`M-x psychoanalyze-pinhead'
     Let Emacs psychoanalyze Zippy.

Customization
*************

Initialization Files
====================

   The operation of Win-Emacs can be controlled by initialization files
located in the directory specified in the environment variable
`EMACSHOME', or `HOME' if `EMACSHOME' does not exist, or in `c:\' if
neither environment variable exists.  The most commonly used startup
files are `emacs.ini' and `xdefault.ini'.  It is not necessary for
either file to exist; Win-Emacs provides reasonable defaults for all
configurable options.

The file `emacs.ini'
--------------------

   The file `emacs.ini' contains arbitrary Emacs-Lisp code to be
executed at startup and is the equivalent of the Unix `.emacs' file.
Keys can be rebound, options can be set, etc.  For example:

     (global-set-key "\C-x\C-j" 'goto-line)

   causes the key sequence `C-x C-j' (`C-x' is Emacs lingo for
`Control-x'; similarly, `M-x' means `Meta-x', which in Win-Emacs means
press `Alt-x' or `ESC x') to execute the Emacs-Lisp command
`goto-line', which will prompt for a line number to move to.  For more
information on Emacs commands, *Note More Documentation::.

   For compatibility with earlier versions of Win-Emacs, E-Lisp commands
will also be loaded out of the file `_emacs' if it exists.  You should
not use this, however; use `emacs.ini' instead.

The file `xdefault.ini'
-----------------------

   The file `xdefault.ini' allows the startup fonts, colors, and other
graphical options (called "resources") to be specified.  (This is
equivalent to the X Windows `.Xdefaults' file and has the same format.)
Each line of this file specifies a resource pattern and a value,
separated by a colon.

Introduction to Resources
.........................

   A "resource pattern" is either the name of a resource or a wildcard
specification (matching a number of resources), similar to a wildcard
filename specification.  The resources themselves are named
hierarchically, similar to names in the file system.  As a hypothetical
example, consider a program named `Quark'.  This program might have a
resource to specify the language that messages should be printed out
in, and its name might be `Quark.language'.  Then, a simple resource
specification might be

     Quark.language: Swahili

   Quark might also have resources to control its colors, fonts, etc.
Perhaps this program has a menubar, a display area, an edit area, an
error area, etc.  Each of these areas can have its own font, foreground
color, background color, size, and so on.  In such a case, a sub-level
would probably be used; then there would exist resources
`Quark.menubar.font', `Quark.menubar.foreground',
`Quark.menubar.background', `Quark.display.font',
`Quark.display.foreground', `Quark.display.background', etc.  If you
want to set the display area's foreground color to dark green, then you
could say

     Quark.display.foreground: dark green

   What if you wanted to set all foreground colors at once?  Then you
could say

     Quark*foreground: red

   The asterisk substitutes for zero or more levels in between; thus it
would set resources called `Quark.display.foreground' and
`Quark.menubar.foreground' and `Quark.error_area.foreground', and also
`Quark.grapher.menubar.foreground' and
`Quark.grapher.error_area.foreground' and so on.

   What if you wanted to set all foreground colors to red, *except*
that you wanted the display area to be dark green?  Then you would say
something like:

     Quark*foreground: red
     Quark.display.foreground: dark green

   The more specific pattern overrides the more general one. (The same
thing would happen if you reversed the order of the above two lines.
The order of lines in `xdefault.ini' doesn't matter.)

Win-Emacs Resources
...................

   Win-Emacs has resources that control foreground colors, background
colors, fonts, cursor colors, cursor shapes, and so on.  A particular
screen (i.e. top-level Windows window) can have its characteristics
specified individually, according to the name of the screen; so can a
particular face, or a particular face on a particular screen.  (By
default all screens are named `emacs', so differentiating by screens
isn't too useful unless you change a screen's name.  This will become
more useful when features like `info' are modified to use their own
screens.) The application name of Win-Emacs is `Emacs'.  Wildcard
resource patterns should always be used, because the actual
fully-qualified resource names may change from release to release.

   For example, to set the font of all screens, you could say:

     Emacs*font: Courier-12

   To set the font on a screen named `myscreen', you could say:

     Emacs*myscreen*font: Courier-12

   To set the background of the modeline face, you could say:

     Emacs*modeline*attributeBackground: goldenrod

   See the file `NEWS' in the `etc' subdirectory for more information
about specific resources.

The file `xmodmap.ini'
----------------------

   This file allows the mapping between logical and physical pointer
buttons to be changed (see also *note Remapping the Pointer::.).  The
format of this file is the same as a standard `.xmodmaprc' file under X
(i.e. input to the `xmodmap' command).  Comments are specified by
beginning a line with a `!', and lines beginning with keywords are
directives that specify mappings.  Currently the only directive that is
processed is the `pointer' directive.  For example, the directive

     pointer = 1 3 2

   assigns logical button 1 to the left mouse button, logical button 3
to the middle mouse button, and logical button 2 to the right mouse
button.  This way, for example, the middle mouse button would bring
down a popup menu and the right mouse button would insert the selected
text at the current mouse position.

Specifying Colors
=================

   A color value is represented internally as a triple of numbers (R,
G, B), specifying (respectively) the intensity of the red, green, and
blue components of the color.  Each number can be between 0 and 255,
with higher values corresponding to brighter colors.

   When Win-Emacs expects you to specify a color, you can do it in one
of two ways: either by giving the RGB values directly or by using a name
(such as `red' or `forest green') that Win-Emacs recognizes.  The
recognized color names are listed in the file `rgb.txt' in the `bin'
subdirectory.  Each line in this file lists the R, G, and B values of
the color followed by its name, which is not case sensitive.  You can
modify this file and add your own color names.

   To specify an RGB value directly, use the format `#RGB' or
`#RRGGBB', where each letter represents a single hexadecimal digit.
For example, the specification `#CAA520' represents the RGB triple
(0xCA, 0xA5, 0x20) or (218, 165, 32) in decimal. (This is equivalent to
the color `goldenrod' in `rgb.txt'.) The format `#RGB' is equivalent to
`#R0G0B0': e.g. `#6A3' is the same as `#60A030', which is the RGB
triple `(0x60, 0xA0, 0x30)' or `(96, 160, 48)' in decimal.

Specifying Fonts
================

   Font names may be specified in one of two ways: A simplified method
that is specific to Win-Emacs, or the standard X/Windows way.  Under
most circumstances, you will want to use the simplified method, because
it is more intuitive.

Simplified Font Form
--------------------

   Fonts can be specified using a simplified form, which is one of the
following:

     NAME-SIZE
     NAME-SIZE-italic
     NAME-SIZE-bold
     NAME-SIZE-bold-italic
     NAME-SIZE-demibold
     NAME-SIZE-demibold-italic

   where NAME is the font family (e.g. `Courier') and SIZE is the size
in points.  For example, `Courier-12' specifies a 12-point
medium-weight upright Courier font and `Fixedsys-9-bold' specifies a
9-point bold-weight upright Fixedsys font.

X/Windows Font Form
-------------------

     (same as "-*-Courier-medium-r-*-*-*-120-*-*-*-*-*")

   Fonts can also be specified in the standard X/Windows format.  You
probably do not need to use this format except under special
circumstances, unless you wish to be compatible with X/Windows.  Fonts
in X/Windows have long names that begin with a dash, such as

     -adobe-courier-medium-r-normal--12-120-100-100-m-100-iso-8859-1

   The sections of the font name have meanings as follows:

     -[1]-[2]-[3]-[4]-[5]-[6]-[7]-[8]-[9]-[10]-[11]-[12]-[13]

   where

     [1] = foundry that produced the font
     [2] = font family name
     [3] = weight (`medium' or `bold' or `demibold')
     [4] = slant (`r' (upright) or `o' (oblique) or `i' (italic))
     [5] = set width (usually `normal'; could be `semicondensed',
     `condensed', `narrow', `double width', etc.)
     [6] = serif (blank or `sans')
     [7] = pixels
     [8] = points (in tenths of a point)
     [9] = horizontal resolution in dpi
     [10] = vertical resolution in dpi
     [11] = spacing (`m' (monospace) or `p' (proportional))
     [12] = average width (in tenths of a pixel)
     [13] = character set (usually `iso8859-1')

   Specifying fonts in this fashion gives a great deal of information
about the font.  However, it's rather inconvenient to have to specify
long names like this, so X provides a wildcarding mechanism.  Whenever
a font is called for, a "font specification" can be given where an
asterisk substitutes for 0 or more characters in a font name, very
similar to wildcards in a filename.  For example, under X the font
specification

     -*-courier-medium-r-*-120-*	(** DOES NOT WORK IN WIN-EMACS **)

   matches the fully-qualified font name given above, and also matches
any other Courier 12-point medium upright font that exists on the
system.

   Win-Emacs supports font specifications; however, its wildcarding
mechanism is incomplete, and an asterisk can only be used to substitute
for exactly one section of the font name.  For example, the font
specification

     -*-courier-medium-r-*-*-*-120-*-*-*-*-*	(** WORKS IN WIN-EMACS **)

   is equivalent to the one above and is valid under Win-Emacs.

   (This restriction is likely to be removed in a future release.)

   Notes about particular sections:

[1]
     Under X/Windows, the "foundry" is the corporation that designed the
     font.  Under Win-Emacs, the foundry is one of `raster', `vector',
     or `TrueType', specifying the type of font.  Raster fonts are
     stored as bitmaps and are designed for a particular size, but can
     be scaled up in integral multiples of this size.  Vector fonts are
     an old type of fonts, not used much any more, that are arbitrarily
     scalable but very slow to draw.  TrueType fonts are a new type of
     fonts present starting in Windows 3.1, that are fast and are
     arbitrarily scalable to different sizes.

[4]
     Under Win-Emacs, there is no difference between `italic' and
     `oblique'.

[5]
     The set width is always `normal' under Win-Emacs.

[6]
     The serif is always blank, even for sans-serif fonts, because
     Win-Emacs cannot determine whether a font has serifs or not.

[8]
     A "point" is a unit approximately equal to 1/72 of an inch.

Font Names
----------

   The following fixed-width font names and sizes come standard with
Windows:

   * Courier (10-point, 12-point, 15-point)

   * Courier New (any point size)

   * Fixedsys (9-point)

Binding Keys
============

   Win-Emacs allows for extremely flexible customization of key
bindings.  Almost any "chord", or combination of a key with zero or
more of the Control, Meta, ("Alt" or "Esc"), and Shift modifiers, can
be bound separately from any other chord.  Bindings are not limited to
key/modifier combinations that have ASCII character representations.
Chords can be bound to an arbitarily long sequence of other chords, to
an arbitary Emacs-Lisp function, or to nothing at all.  Furthermore, a
sequence of chords can have its own binding if all but the last chord
in the sequence is defined as a "prefix".  For example, `C-x' is
usually a prefix, allowing the sequence `C-x C-f' to be bound to the
Emacs-Lisp function `find-file'. (See the Emacs-Lisp documentation for
detailed information about prefixes.)

Where to Look for More Documentation
************************************

   * There is extensive on-line documentation (called "Info"), which
     can be retrieved from within Emacs by choosing the `Info' option
     from the `Help' menu or by typing `C-h i'.  This documentation
     explains how to use Win-Emacs as an editor, how to program in
     Emacs-Lisp, how to add more on-line documentation, and how to use
     the various Emacs extensions.  The documentation in Info is
     structured as hypertext, meaning that it is text that contains
     links to other text.  The links are displayed in boldface and
     highlight (normally in green) when you move the mouse over them.
     To follow a link, just click the mouse on it.  Other commands are
     available by clicking the right mouse button to bring up a pop-up
     menu of commands.

   * If you are unfamiliar with Emacs, you can access a guided tutorial
     by choosing the `Tutorial' option from the `Help' menu or by
     typing `C-h t'.

   * Sample `emacs.ini' and `xdefault.ini' files are available in the
     `etc' subdirectory in the Win-Emacs distribution.

   * You can obtain help on a specific key or key sequence by choosing
     the `Describe Key...' option from the `Help' menu or by typing
     `C-h k'.  When prompted for a key, type in a key sequence (for
     example, `C-x C-f').  Documentation will be displayed in a
     separate window; type `C-x 1' to get rid of the window.

   * Similarly, you can obtain help on a specific function by choosing
     the `Describe Function...' option from the `Help' menu or by
     typing `C-h f', and on a specific variable by choosing the
     `Describe Variable...' option from the `Help' menu or by typing
     `C-h v'

   * If you are not sure of the name of a command but have some idea of
     its name, you can use the `Command Apropos...' option of the
     `Help' menu (also available by typing `C-h a').  This will prompt
     you for a string and list all commands containing that string in
     their name. (The string you enter is actually a regular
     expression.)

   * The file `etc/NEWS' provides specific information about Emacs 19
     additions.  You can read this file conveniently by choosing the
     `Emacs News' option from the `Help' menu or by typing `C-h n'.

Bugs/Help/Crashes
*****************

   There is extensive on-line documentation available; see the previous
chapter for details.

   If you think you have discovered a bug in Win-Emacs, you can send
e-mail to the Win-Emacs list `win-emacs@pearlsoft.com'; others may have
seen the problem and can give you advice. (The technical people at Pearl
all read this list, and will respond as necessary.) This is also a very
good source if you can't figure out how something works or are unclear
about something.  Make sure you give an exact description of what is
going on, including what you tried to do, the symptoms you see, the text
of any error or warning messages you get, your hardware/software
configuration (mention especially anything you have that might be
unusual), and (if possible) a recipe for reproducing the problem.

   You can also contact Pearl Software directly (*Note Contacting Pearl
Software::).

   Before you ask about a bug, however, keep in mind that the following
are known limitations in the current version of Win-Emacs:

   * Support for italicized and variable-width fonts is not perfect.

   * Win-Emacs may not always handle resource limitations gracefully.
     In some circumstances it may crash when it runs out of memory.

   * Asynchronous subprocesses are not currently supported.

   In order to guard against power failures and the like, Win-Emacs
frequently "auto-saves" your files, meaning that it saves copies of
what is in the buffer currently.  The name of the auto-save file is
similar to the name of the file, but with `#' characters appended and
prepended.  For example, the auto-save file for `mytest.c' would be
called `#mytest.c#'. (See *note MS-DOS Filenames::. for more information
on auto-save file names.)

   You can recover the contents of the file from its auto-save file
using the command `M-x recover-file'.  This displays the sizes and dates
of the file and its auto-save file, and lets you choose whether to
recover the file.  Win-Emacs will automatically remind you about using
`M-x recover-file' whenever you visit a file that has an auto-save file
that is more recent than the time that the file was last saved.

   Any time that Win-Emacs crashes due to an internal error or is killed
(e.g. when you exit Windows), it attempts to auto-save all current
buffers.  If Win-Emacs crashes, you will probably see a message box that
says `Fatal Error in Win-Emacs!' or `Assertion Failure'.  If so, please
report the problem to Pearl Software as described above, and we will
try to eliminate it as soon as possible.

Differences From Other Emacsen
******************************

   Please look in the file `NEWS' in the `etc' subdirectory for more
information.  This file documents the differences between Emacs 18 and
Lucid Emacs 19.6.

Obtaining Source Code
*********************

   Source code for the Emacs DLL and for the Emacs-Lisp files can be
FTP'ed from `ftp.netcom.com:/pub/pearl'.  The Emacs DLL source code is
in the form of diffs; in order to construct the source files, you will
need to obtain the Lucid-Emacs 19.6, X Library, and X Toolkit sources.
See the `README' file at the FTP site for more information.

   The full source code (not in diff form) can also be ordered from us
for a shipping/handling fee.  Please contact us for more information.

Questions, Comments, Problems, Bug Reports
******************************************

   Pearl Software is reachable by e-mail at:

`tech@pearlsoft.com'
     For technical questions about the product (whether a particular
     feature is implemented, how to use a particular package, why
     something doesn't seem to work, etc.).

`sales@pearlsoft.com'
     How to order the product, support contracts, upgrades, etc.

`info@pearlsoft.com'
     This is an auto-reply message that gives an introduction to
     Win-Emacs, specifies how to get it, etc.  Since this is an
     auto-reply, do *not* send anything to this address that you want a
     human to reply to!  It will get discarded.

`listserv@pearlsoft.com'
     This is Pearl Software's mail server, which allows you to obtain
     files about Win-Emacs, find out about the available mailing lists,
     determine which lists you're on, etc.  Keep in mind that there is
     a computer on the other end of this address: Thus, you need to
     send special commands that it understands.  For details, send a
     one-line message containing the word word `help' to this address.

   As of the writing of this guide, the following mailing lists are
maintained by Pearl Software:

`win-emacs@pearlsoft.com'
     A general discussion group about Win-Emacs.  To subscribe, send
     mail to `win-emacs-request@pearlsoft.com' containing just the word
     `subscribe' in its body.

`announcement@pearlsoft.com'
     Group to which announcements of new releases of Win-Emacs and
     similar information is sent.  To subscribe, send mail to
     `announcement-request@pearlsoft.com' containing just the word
     `subscribe' in its body.

   You can also contact Pearl Software at

     2000 Powell St.
     Suite 1200
     Emeryville, CA 94608
     
     voice: 510-652-4361
     fax: 510-652-4362

