Mercurial > emacs

--- a/man/msdog.texi	Fri Apr 21 09:24:43 2006 +0000
+++ b/man/msdog.texi	Fri Apr 21 11:41:16 2006 +0000
@@ -5,22 +5,26 @@
 @node Emacs and Microsoft Windows, Manifesto, Mac OS, Top
 @appendix Emacs and Microsoft Windows
 @cindex Microsoft Windows
+@cindex MS-Windows, Emacs peculiarities

   This section describes peculiarities of using Emacs on Microsoft
-Windows.  Information about Emacs and Microsoft's older MS-DOS
-``operating system'' (also known as ``MS-DOG'') is now in a separate
-manual (@inforef{MS-DOG,, emacs-xtra}).
+Windows.  Some of these peculiarities are also relevant to Microsoft's
+older MS-DOS ``operating system'' (also known as ``MS-DOG'').
+However, Emacs features that are relevant @emph{only} to MS-DOS are
+now described in a separate manual (@inforef{MS-DOG,, emacs-xtra}).

-  Iif you want to use Emacs on Windows, you would normally build Emacs
-specifically for Windows.  If you do that, the behavior is reasonably
-similar to what is documented in the rest of the manual, including
-support for long file names, multiple frames, scroll bars, mouse
-menus, and subprocesses.  However, a few special considerations apply,
-and they are described here.
+  The behavior of Emacs on MS-Windows is reasonably similar to what is
+documented in the rest of the manual, including support for long file
+names, multiple frames, scroll bars, mouse menus, and subprocesses.
+However, a few special considerations apply, and they are described
+here.

 @menu
 * Text and Binary::            Text files use CRLF to terminate lines.
+* Windows Files::              File-name conventions on Windows.
+* Windows HOME::               Where Emacs looks for your @file{.emacs}.
 * Windows Processes::          Running subprocesses on Windows.
+* Windows Printing::           How to specify the printer on MS-Windows.
 * Windows System Menu::        Controlling what the ALT key does.
 @end menu

@@ -29,11 +33,11 @@
 @cindex text and binary files on MS-DOS/MS-Windows

   GNU Emacs uses newline characters to separate text lines.  This is the
-convention used on GNU and Unix.
+convention used on GNU, Unix, and other Posix-compliant systems.

 @cindex end-of-line conversion on MS-DOS/MS-Windows
-  MS-DOS and MS-Windows normally use carriage-return linefeed, a
-two-character sequence, to separate text lines.  (Linefeed is the same
+  By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed,
+a two-character sequence, to separate text lines.  (Linefeed is the same
 character as newline.)  Therefore, convenient editing of typical files
 with Emacs requires conversion of these end-of-line (EOL) sequences.
 And that is what Emacs normally does: it converts carriage-return
@@ -57,11 +61,11 @@

   The mode line indicates whether end-of-line translation was used for
 the current buffer.  If MS-DOS end-of-line translation is in use for the
-buffer, a backslash @samp{\} is displayed after the coding system
-mnemonic near the beginning of the mode line (@pxref{Mode Line}).  If no
-EOL translation was performed, the string @samp{(Unix)} is displayed
-instead of the backslash, to alert you that the file's EOL format is not
-the usual carriage-return linefeed.
+buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after
+the coding system mnemonic near the beginning of the mode line
+(@pxref{Mode Line}).  If no EOL translation was performed, the string
+@samp{(Unix)} is displayed instead of the backslash, to alert you that the
+file's EOL format is not the usual carriage-return linefeed.

 @cindex DOS-to-Unix conversion of files
   To visit a file and specify whether it uses DOS-style or Unix-style
@@ -78,14 +82,14 @@

 @cindex untranslated file system
 @findex add-untranslated-filesystem
-  When you use NFS or Samba to access file systems that reside on
-computers using GNU or Unix systems, Emacs should not perform
-end-of-line translation on any files in these file systems---not even
-when you create a new file.  To request this, designate these file
-systems as @dfn{untranslated} file systems by calling the function
-@code{add-untranslated-filesystem}.  It takes one argument: the file
-system name, including a drive letter and optionally a directory.  For
-example,
+  When you use NFS, Samba, or some other similar method to access file
+systems that reside on computers using GNU or Unix systems, Emacs
+should not perform end-of-line translation on any files in these file
+systems---not even when you create a new file.  To request this,
+designate these file systems as @dfn{untranslated} file systems by
+calling the function @code{add-untranslated-filesystem}.  It takes one
+argument: the file system name, including a drive letter and
+optionally a directory.  For example,

 @example
 (add-untranslated-filesystem "Z:")
@@ -103,7 +107,7 @@
 system.

   Most often you would use @code{add-untranslated-filesystem} in your
-@file{_emacs} file, or in @file{site-start.el} so that all the users at
+@file{.emacs} file, or in @file{site-start.el} so that all the users at
 your site get the benefit of it.

 @findex remove-untranslated-filesystem
@@ -120,9 +124,9 @@
 @vindex file-name-buffer-file-type-alist
 @cindex binary files, on MS-DOS/MS-Windows
   Some kinds of files should not be converted at all, because their
-contents are not really text.  Therefore, Emacs on MS-DOS distinguishes
+contents are not really text.  Therefore, Emacs on MS-Windows distinguishes
 certain files as @dfn{binary files}.  (This distinction is not part of
-MS-DOS; it is made by Emacs only.)  Binary files include executable
+MS-Windows; it is made by Emacs only.)  Binary files include executable
 programs, compressed archives, etc.  Emacs uses the file name to decide
 whether to treat a file as binary: the variable
 @code{file-name-buffer-file-type-alist} defines the file-name patterns
@@ -132,29 +136,88 @@
 @code{no-conversion} coding system (@pxref{Coding Systems}) which turns
 off @emph{all} coding-system conversions, not only the EOL conversion.
 @code{file-name-buffer-file-type-alist} also includes file-name patterns
-for files which are known to be DOS-style text files with
+for files which are known to be Windows-style text files with
 carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs
-always writes those files with DOS-style EOLs.
+always writes those files with Windows-style EOLs.

   If a file which belongs to an untranslated file system matches one of
 the file-name patterns in @code{file-name-buffer-file-type-alist}, the
 EOL conversion is determined by @code{file-name-buffer-file-type-alist}.

+@node Windows Files
+@section File Names on MS-Windows
+@cindex file names on MS-Windows
+
+  MS-Windows and MS-DOS normally use a backslash, @samp{\}, to
+separate name units within a file name, instead of the slash used on
+other systems.  Emacs on MS-DOS/MS-Windows permits use of either slash or
+backslash, and also knows about drive letters in file names.
+
+@cindex file-name completion, on MS-Windows
+  On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by
+default ignores letter-case in file names during completion.
+
+@node Windows HOME
+@section HOME Directory on MS-Windows
+@cindex @code{HOME} directory on MS-Windows
+
+  The MS-Windows equivalent of the @code{HOME} directory is the
+@dfn{user-specific application data directory}.  The actual location
+depends on your Windows version and system configuration; typical values
+are @file{C:\Documents and Settings\@var{username}\Application Data} on
+Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data}
+or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the
+older Windows 9X/ME systems.
+
+@cindex init file @file{.emacs} on MS-Windows
+  The home directory is where your init file @file{.emacs} is stored.
+When Emacs starts, it first checks whether the environment variable
+@env{HOME} is set.  If it is, it looks for the init file in the
+directory pointed by @env{HOME}.  If @env{HOME} is not defined, Emacs
+checks for an existing @file{.emacs} file in @file{C:\}, the root
+directory of drive @file{C:}@footnote{
+The check in @file{C:\} is in preference to the application data
+directory for compatibility with older versions of Emacs, which didn't
+check the application data directory.
+}.  If there's no such file in @file{C:\}, Emacs next uses the Windows
+system calls to find out the exact location of your application data
+directory.  If that fails as well, Emacs falls back to @file{C:\}.
+
+  Whatever the final place is, Emacs sets the value of the @env{HOME}
+environment variable to point to it, and it will use that location for
+other files and directories it normally creates in the user's home
+directory.
+
+  You can always find out where Emacs thinks is your home directory's
+location by typing @kbd{C-x d ~/ @key{RET}}.  This should present the
+list of files in the home directory, and show its full name on the
+first line.  Likewise, to visit your init file, type @kbd{C-x C-f
+~/.emacs @key{RET}}.
+
+@cindex @file{_emacs} init file, MS-Windows
+  Because MS-DOS does not allow file names with leading dots, and
+because older Windows systems made it hard to create files with such
+names, the Windows port of Emacs supports an alternative name
+@file{_emacs} as a fallback, if such a file exists in the home
+directory, whereas @file{.emacs} does not.
+
 @node Windows Processes
-@section Subprocesses on Windows 9X/ME and Windows NT/2K
+@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP
+@cindex subprocesses on MS-Windows

+@cindex DOS applications, running from Emacs
   Emacs compiled as a native Windows application (as opposed to the DOS
 version) includes full support for asynchronous subprocesses.
 In the Windows version, synchronous and asynchronous subprocesses work
 fine on both
-Windows 9X and Windows NT/2K as long as you run only 32-bit Windows
+Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows
 applications.  However, when you run a DOS application in a subprocess,
 you may encounter problems or be unable to run the application at all;
 and if you run two DOS applications at the same time in two
 subprocesses, you may have to reboot your system.

 Since the standard command interpreter (and most command line utilities)
-on Windows 95 are DOS applications, these problems are significant when
+on Windows 9X are DOS applications, these problems are significant when
 using that system.  But there's nothing we can do about them; only
 Microsoft can fix them.

@@ -174,13 +237,14 @@
 subprocesses, the second one that is started will be suspended until the
 first one finishes, even if either or both of them are asynchronous.

+@cindex kill DOS application
 If you can go to the first subprocess, and tell it to exit, the second
 subprocess should continue normally.  However, if the second subprocess
 is synchronous, Emacs itself will be hung until the first subprocess
 finishes.  If it will not finish without user input, then you have no
 choice but to reboot if you are running on Windows 9X.  If you are
-running on Windows NT/2K, you can use a process viewer application to kill
-the appropriate instance of ntvdm instead (this will terminate both DOS
+running on Windows NT/2K/XP, you can use a process viewer application to kill
+the appropriate instance of NTVDM instead (this will terminate both DOS
 subprocesses).

 If you have to reboot Windows 9X in this situation, do not use the
@@ -189,16 +253,156 @@
 @code{Shutdown}.  That usually works, although it may take a few minutes
 to do its job.

+@node Windows Printing
+@section Printing and MS-Windows
+
+  Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and
+@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and
+MS-Windows by sending the output to one of the printer ports, if a
+Posix-style @code{lpr} program is unavailable.  The same Emacs
+variables control printing on all systems, but in some cases they have
+different default values on MS-DOS and MS-Windows.
+
+  Emacs on Windows automatically determines your default printer and
+sets the variable @var{printer-name} to that printer's name.  But in
+some rare cases this can fail, or you may wish to use a different
+printer from within Emacs.  The rest of this section explains how to
+tell Emacs which printer to use.
+
+@vindex printer-name@r{, (MS-DOS/MW-Windows)}
+  If you want to use your local printer, then set the Lisp variable
+@code{lpr-command} to @code{""} (its default value on Windows) and
+@code{printer-name} to the name of the printer port---for example,
+@code{"PRN"}, the usual local printer port or @code{"LPT2"}, or
+@code{"COM1"} for a serial printer.  You can also set
+@code{printer-name} to a file name, in which case ``printed'' output
+is actually appended to that file.  If you set @code{printer-name} to
+@code{"NUL"}, printed output is silently discarded (sent to the system
+null device).
+
+  You can also use a printer shared by another machine by setting
+@code{printer-name} to the UNC share name for that printer---for
+example, @code{"//joes_pc/hp4si"}.  (It doesn't matter whether you use
+forward slashes or backslashes here.)  To find out the names of shared
+printers, run the command @samp{net view} from the command prompt to
+obtain a list of servers, and @samp{net view @var{server-name}} to see
+the names of printers (and directories) shared by that server.
+Alternatively, click the @samp{Network Neighborhood} icon on your
+desktop, and look for machines which share their printers via the
+network.
+
+@cindex @samp{net use}, and printing on MS-Windows
+@cindex networked printers (MS-Windows)
+  If the printer doesn't appear in the output of @samp{net view}, or
+if setting @code{printer-name} to the UNC share name doesn't produce a
+hardcopy on that printer, you can use the @samp{net use} command to
+connect a local print port such as @code{"LPT2"} to the networked
+printer.  For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{
+Note that the @samp{net use} command requires the UNC share name to be
+typed with the Windows-style backslashes, while the value of
+@code{printer-name} can be set with either forward- or backslashes.}
+causes Windows to @dfn{capture} the @code{LPT2} port and redirect the
+printed material to the printer connected to the machine @code{joes_pc}.
+After this command, setting @code{printer-name} to @code{"LPT2"}
+should produce the hardcopy on the networked printer.
+
+  With some varieties of Windows network software, you can instruct
+Windows to capture a specific printer port such as @code{"LPT2"}, and
+redirect it to a networked printer via the @w{@code{Control
+Panel->Printers}} applet instead of @samp{net use}.
+
+  If you set @code{printer-name} to a file name, it's best to use an
+absolute file name.  Emacs changes the working directory according to
+the default directory of the current buffer, so if the file name in
+@code{printer-name} is relative, you will end up with several such
+files, each one in the directory of the buffer from which the printing
+was done.
+
+@findex print-buffer @r{(MS-DOS)}
+@findex print-region @r{(MS-DOS)}
+@vindex lpr-headers-switches @r{(MS-DOS)}
+  The commands @code{print-buffer} and @code{print-region} call the
+@code{pr} program, or use special switches to the @code{lpr} program, to
+produce headers on each printed page.  MS-DOS and MS-Windows don't
+normally have these programs, so by default, the variable
+@code{lpr-headers-switches} is set so that the requests to print page
+headers are silently ignored.  Thus, @code{print-buffer} and
+@code{print-region} produce the same output as @code{lpr-buffer} and
+@code{lpr-region}, respectively.  If you do have a suitable @code{pr}
+program (for example, from GNU Coreutils), set
+@code{lpr-headers-switches} to @code{nil}; Emacs will then call
+@code{pr} to produce the page headers, and print the resulting output as
+specified by @code{printer-name}.
+
+@vindex print-region-function @r{(MS-DOS)}
+@cindex lpr usage under MS-DOS
+@vindex lpr-command @r{(MS-DOS)}
+@vindex lpr-switches @r{(MS-DOS)}
+  Finally, if you do have an @code{lpr} work-alike, you can set the
+variable @code{lpr-command} to @code{"lpr"}.  Then Emacs will use
+@code{lpr} for printing, as on other systems.  (If the name of the
+program isn't @code{lpr}, set @code{lpr-command} to specify where to
+find it.)  The variable @code{lpr-switches} has its standard meaning
+when @code{lpr-command} is not @code{""}.  If the variable
+@code{printer-name} has a string value, it is used as the value for the
+@code{-P} option to @code{lpr}, as on Unix.
+
+@findex ps-print-buffer @r{(MS-DOS)}
+@findex ps-spool-buffer @r{(MS-DOS)}
+@vindex ps-printer-name @r{(MS-DOS)}
+@vindex ps-lpr-command @r{(MS-DOS)}
+@vindex ps-lpr-switches @r{(MS-DOS)}
+  A parallel set of variables, @code{ps-lpr-command},
+@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript
+Variables}), defines how PostScript files should be printed.  These
+variables are used in the same way as the corresponding variables
+described above for non-PostScript printing.  Thus, the value of
+@code{ps-printer-name} is used as the name of the device (or file) to
+which PostScript output is sent, just as @code{printer-name} is used
+for non-PostScript printing.  (There are two distinct sets of
+variables in case you have two printers attached to two different
+ports, and only one of them is a PostScript printer.)
+
+  The default value of the variable @code{ps-lpr-command} is @code{""},
+which causes PostScript output to be sent to the printer port specified
+by @code{ps-printer-name}, but @code{ps-lpr-command} can also be set to
+the name of a program which will accept PostScript files.  Thus, if you
+have a non-PostScript printer, you can set this variable to the name of
+a PostScript interpreter program (such as Ghostscript).  Any switches
+that need to be passed to the interpreter program are specified using
+@code{ps-lpr-switches}.  (If the value of @code{ps-printer-name} is a
+string, it will be added to the list of switches as the value for the
+@code{-P} option.  This is probably only useful if you are using
+@code{lpr}, so when using an interpreter typically you would set
+@code{ps-printer-name} to something other than a string so it is
+ignored.)
+
+  For example, to use Ghostscript for printing on the system's default
+printer, put this in your @file{.emacs} file:
+
+@example
+(setq ps-printer-name t)
+(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe")
+(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH"
+			"-sDEVICE=mswinpr2"
+			"-sPAPERSIZE=a4"))
+@end example
+
+@noindent
+(This assumes that Ghostscript is installed in the
+@file{D:/gs6.01} directory.)
+
 @node Windows System Menu
 @section Using the System Menu on Windows
+@cindex @code{Alt} key invokes menu (Windows)

 Emacs compiled as a native Windows application normally turns off the
-Windows feature that tapping the @key{ALT}
-key invokes the Windows menu.  The reason is that the @key{ALT} also
-serves as @key{META} in Emacs.  When using Emacs, users often press the
-@key{META} key temporarily and then change their minds; if this has the
-effect of bringing up the Windows menu, it alters the meaning of
-subsequent commands.  Many users find this frustrating.
+Windows feature that tapping the @key{ALT} key invokes the Windows
+menu.  The reason is that the @key{ALT} serves as @key{META} in Emacs.
+When using Emacs, users often press the @key{META} key temporarily and
+then change their minds; if this has the effect of bringing up the
+Windows menu, it alters the meaning of subsequent commands.  Many
+users find this frustrating.

 @vindex w32-pass-alt-to-system
 You can re-enable Windows' default handling of tapping the @key{ALT} key