[xorg-commit-diffs] xc/programs/Xserver/hw/xwin XWinrc.man, NONE, 1.1.2.1 Imakefile, 1.1.4.1.2.14, 1.1.4.1.2.15 XWin.man, 1.1.4.1.2.4, 1.1.4.1.2.5

[Harold L Hunt II]

Committed by: harold

Update of /cvs/xorg/xc/programs/Xserver/hw/xwin
In directory pdx:/tmp/cvs-serv18314

Modified Files:
      Tag: CYGWIN
	Imakefile XWin.man 
Added Files:
      Tag: CYGWIN
	XWinrc.man 
Log Message:
Add new XWinrc man page.  (Rodrigo Medina)

--- NEW FILE: XWinrc.man ---
.TH XWIN 5 __vendorversion__


.SH NAME
XWinrc\- XWin Server Resource Configuration File.


.SH DESCRIPTION
The X Server for the X Window System on the Cygwin/X environment
running on Microsoft Windows, \fIXWin\fP can be optionally configured
with the \fIXWinrc\fP file. A system-wide configuration file should
be placed in \fI/usr/X11R6/lib/X11/system.XWinrc\fP, a per-user
file should be put at \fI$HOME/.XWinrc\fP. The \fIsystem.XWinrc\fP file is read
only if no \fI$HOME/.XWinrc\fP exist.
.PP
With the \fI.XWinrc\fP configuration file it is possible to do the following:
.PP
1- To include items into the menu associated with the \fIXWin\fP icon
which is in the \fIWindows\fP system tray. This feature functions in all
XWin  modes that have such tray icon.
.PP
2- To include items into the menu which is associated with the \fIWindows\fP
window that \fIXWin -multiwindow\fP produces for each top-level X-window.
That can be done both for the generic case and for particular programs.
.PP
3- To change the icon that is associated to the \fIWindows\fP window that
\fIXWin -multiwindow\fP produces for each top-level X-window. Again, that
can be done both for the generic case and for particular programs. The new
icons associated should be \fIWindows\fP kind incons \fI.ico\fP.


.SH FILE FORMAT
.B Keywords
are case insensitive, but in this document they will be written
completely capitalized.
.PP
.B Comments
are legal pretty much anywhere you can have an end-of-line; they
begin with "#" or "//" and go to the end-of-line.
.PP
Quote marks in strings are optional unless the string has included spaces.
.PP
There are three kinds of instructions, debug, menu and icon instructions.


.SH Debug instruction
.TP 8
.B DEBUG \fIString\fP
The \fIString\fP is printed to the XWin.log file.


.SH Menu instructions
.TP 8
.B MENU \fIMenu_Name\fP {
.br
.B       \fIMenu_Item_Line\fP
.br
.B       \fIMenu_Item_Line\fP
.br
.B        \fI...\fP
.br
.B }
.br
This instruction defines a menu and asigns a \fIMenu_Name\fP to it.
\fIMenu_Item_Line\fP are lines  of any of the following types:
.TP 8
.B \t SEPARATOR
.TP 8
.B  \t \fIItem_Label\fP  EXEC \fICommand\fP
.TP 8
.B \t \fIItem_Label\fP  MENU \fIpreviously-defined-menu-name\fP
.TP 8
.B \t \fIItem_Label\fP  ALWAYSONTOP
.TP 8
.B \t \fIItem_Label\fP  RELOAD
.br
The \fIItem_Label\fP is the string that is written in the menu item.
.br
\fICommand\fP is a string with the command that will be executed. Here
paths should be \fICYGWIN\fP style (e.g. /usr/local/bin/myprogram).
A string "%display%" appearing in the \fICommand\fP will be replaced
with the proper display variable (i.e. 127.0.0.1:<display>.0).
.br
\fBALWAYSONTOP\fP sets the window to which the menu is associated to
display above all others.
.br
\fBRELOAD\fP causes the XWinrc file to be reloaded and icons and menus
regenerated.
.TP 8
.B ROOTMENU \fIpreviously-defined-menu-name\fP
Includes the items in the indicated menu into the menu associated with
\fIXWin\fP that appears in the system tray.
.TP 8
.B DEFAULTSYSMENU \fIpreviously-defined-menu-name\fP ATSTART|ATEND
Includes the items in the indicated menu into the menu associated with
generic top-level X-Windows in the \fIXWin\fP \fImultiwindow\fP mode. The
keywords \fBATSTART\fP and \fBATEND\fP indicate if such items should be
included at the start or at the end of the menu.
.TP 8
.B SYSMENU {
  \fIclass-or-name-of-window\fP \fIdefined-menu-name\fP \fBATSTART|ATEND\fP
.br
  \fI...\fP
.br
  \fB}\fP
.br
Associates a specific menu to a specific WM_CLASS or WM_NAME.


.SH Icon Instructions
.TP 8
.B ICONDIRECTORY \fIWindows-path-to-icon-directory\fP
Defines the directory where the \fI.ico\fP files are located. It should
be a \fIWindows\fP style path (e.g. C:\\cygwin\\usr\\local\\icons).
.TP 8
.B DEFAULTICON \fIicon-file-name.ico\fP
Defines a replacement for the standard X icon for applications without
specified icons.
.TP 8
.B ICONS {
 \fIclass-or-name-of-window\fP \fIicon-file-name.ico\fP
.br
  \fI...\fP
.br
  \fB}\fP
.br
Defines icon replacements for specific windows.


.SH "SEE ALSO"
 XWin(1)


.SH AUTHOR
The XWinrc feature of XWin was written primarily by Earle F. Philhower
III.

Index: Imakefile
===================================================================
RCS file: /cvs/xorg/xc/programs/Xserver/hw/xwin/Imakefile,v
retrieving revision 1.1.4.1.2.14
retrieving revision 1.1.4.1.2.15
diff -u -d -r1.1.4.1.2.14 -r1.1.4.1.2.15
--- a/Imakefile	3 Apr 2004 05:00:46 -0000	1.1.4.1.2.14
+++ b/Imakefile	14 Apr 2004 00:01:22 -0000	1.1.4.1.2.15
@@ -280,5 +280,6 @@
 NormalLibraryTarget(XWin,$(OBJS))
 
 InstallManPage(XWin,$(MANDIR))
+InstallManPage(XWinrc,$(MANDIR))
 
 DependTarget()

Index: XWin.man
===================================================================
RCS file: /cvs/xorg/xc/programs/Xserver/hw/xwin/XWin.man,v
retrieving revision 1.1.4.1.2.4
retrieving revision 1.1.4.1.2.5
diff -u -d -r1.1.4.1.2.4 -r1.1.4.1.2.5
--- a/XWin.man	29 Mar 2004 15:45:52 -0000	1.1.4.1.2.4
+++ b/XWin.man	14 Apr 2004 00:01:22 -0000	1.1.4.1.2.5
@@ -1,124 +1,281 @@
-.\" $XFree86: xc/programs/Xserver/hw/xwin/XWin.man,v 1.5 2002/07/05 09:19:25 alanh Exp $
 .TH XWIN 1 __vendorversion__
 .SH NAME
 XWin \- X Server for the Cygwin environment on Microsoft Windows
+
+
 .SH SYNOPSIS
 .B XWin
 [ options ] ...
+
+
 .SH DESCRIPTION
-.I XWin
-is an X Server for the X Window System on the Cygwin environment
+.I XWin is an X Server for the X Window System on the Cygwin environment
 running on Microsoft Windows.
-.SH OPTIONS
+
+
+.SH MODES
+\fIXWin\fP can operate in five different and incompatible modes:
+.br
+* \fISingle Window\fP: This is the default option.  The X server
+appears as a single Windows window and all X windows are contained
+within this window.  This mode requires an external window manager.
+.br
+* \fINo Decoration\fP: This mode is like single window mode except
+that the X server window does not have a title bar or border, thus
+maximizing the amount of space available for X windows within the X
+server window.  This mode requires an external window manager.
+.br
+* \fIFull Screen\fP: This mode is like single window mode except that
+the X server window takes the full screen, covering completely the
+Windows desktop.  This mode requires an external window manager.
+.br
+* \fIRootless\fP: The X server works on a window covering the whole
+screen but the root window (traditionally covered with an X hatch
+pattern) is hidden from view.  This mode requires an external window
+manager.
+.br
+* \fIMulti-Window\fP: In this mode \fIXWin\fP uses its own integrated
+window manager in order to handle the top-level X windows, in such a
+way that they appear as normal Windows windows.
+.PP
+NOTE: \fIMulti-Window\fP mode will crash if an external window manager
+such as \fItwm\fP or \fIfvwm\fP is launched since \fIMulti-Window\fP
+uses its own internal window manager; all other modes require an
+external window manager in order to move, resize, and perform other
+operations on the individual X windows.
+
+
+.SH LOG
+As it runs \fIXWin\fP writes messages indicating the most relevant events
+to  the console
+from which it was called and to a log file that by default is located at
+\fI/tmp/XWin.log\fP.  This file is mainly for debugging purposes.
+
+
+.SH PREFERENCES FILE
+On startup \fIXWin\fP looks for the file \fI$HOME/.XWinrc\fP or, if
+the previous file does not exist,
+\fI/usr/X11R6/lib/X11/system.XWinrc\fP.  \fI.XWinrc\fP allows setting
+preferences for the following:
+.br
+1- To include items into the menu associated with the \fIXWin\fP icon
+which is in the \fIWindows\fP system tray.  This functions in all
+modes that have a tray icon.
+.br
+2- To include items in the menu which is associated with the Windows
+window that \fIXWin -multiwindow\fP produces for each top-level X
+window.  That can be done both for the generic case and for particular
+programs.
+.br
+3- To change the icon that is associated to the Windows window that
+\fIXWin -multiwindow\fP produces for each top-level X-window. Again,
+that can be done both for the generic case and for particular
+programs.
 .PP
+The format of the \fI.XWinrc\fP file is given in the man page XWinrc(5).
+
+
+.SH OPTIONS
 In addition to the normal server options described in the \fIXserver(1)\fP
-manual page, \fIXWin\fP accepts the following command line switches:
+manual page, \fIXWin\fP accepts the following command line switches,
+\fIall\fP of which are optional:
 .TP 8
-.B "\-depth \fIdepth\fP"
-Specify the color depth, in bits per pixel, to use when running in
-fullscreen with a DirectDraw engine.  This parameter is ignored if
-\fB\-fullscreen\fP is not specified.
+.B \-clipboard
+Enables the integration
+between the Cygwin/X clipboard and Windows clipboard. Do not use in
+conjunction with the \fIxwinclip\fP program.
+.TP 8
+.B "\-clipupdates \fInum_boxes\fP"
+Specify an optional threshold, above which the boxes in a shadow
+update operation will be collected into a GDI clipping region.  The
+clipping region is then used to do a single bit block transfer that is
+constrained to the updated area by the clipping region.  There is some
+overhead involved in creating, installing, destroying, and removing
+the clipping region, thus there may not be much benefit for a small
+number of boxes (less than 10).  It is even possible that this
+functionality does not provide a benefit at any number of boxes; we
+can only determine the usefulness of this feature through testing.
+This parameter works in conjunction with engines 1, 2, and 4 (Shadow
+GDI, Shadow DirectDraw, and Shadow DirectDraw Non-Locking,
+respectively).
 .TP 8
 .B "\-emulate3buttons \fItimeout\fP"
 Emulate a three button mouse; pressing both buttons within
 .I timeout
 milliseconds causes an emulated middle button press.  The default 
 .I timeout
-is 50 milliseconds.
+is 50 milliseconds. Note that most mice with scroll wheel have middle
+button functionality, usually you will need this option only if you have
+a two button mouse without scroll wheel.
+.TP 8
+.B \-emulatepseudo
+Create a depth 8 PseudoColor visual when running in depths 15, 16, 24,
+or 32, collectively known as TrueColor depths.
+ At this date (April 2004) this option is not still operative.
 .TP 8
 .B "\-engine \fIengine_type_id\fP"
-Override the server's automatically supported engine type.  This
+This option, which is intended for Cygwin/X developers,
+overrides the server's automatically supported engine type.  This
 parameter will be ignored if the specified engine type is not
 supported on the current system.  The supported engine type ids are 1
 - Shadow GDI, 2 - Shadow DirectDraw, and 4 - Shadow DirectDraw4.
 Additionally, there is a barely functional experimental engine type id
 16 - Native GDI.
 .TP 8
-.B \-fullscreen
+.B "\-fullscreen [-depth \fIdepth\fP] [-refresh \fIrate_in_Hz\fP]"
 Run the server in fullscreen mode, as opposed to the default windowed
 mode.
 .TP 8
+.B "\-depth \fIdepth\fP"
+Specify the color depth, in bits per pixel, to use when running in
+fullscreen with a DirectDraw engine.  This parameter is ignored if
+\fB\-fullscreen\fP is not specified.
+.TP 8
 .B "\-refresh \fIrate_in_Hz\fP"
 Specify an optional refresh rate to use when running in
 fullscreen with a DirectDraw engine.  This parameter is ignored if
 \fB\-fullscreen\fP is not specified.
 .TP 8
-.B "\-screen \fIscreen_number\fP \fIwidth\fP \fIheight\fP"
-Sets the display resolution for the X server to use on screen
-.I screen_number.
+.B \-help
+Write a help text to the console and to the log file.
+.TP 8
+.B \-ignoreinput
+Ignore keyboard and mouse input. This is usually only used for testing
+and debugging purposes.
+.TP 8
+.B \-[no]keyhook
+Enable [disable] a low-level keyboard hook for catching
+special key combinations like Alt+Tab and passing them to the X
+Server instead of letting \fIWindows\fP handle them.
+.TP 8
+.B \-lesspointer
+Hide the Windows mouse cursor when the mouse is over any Cygwin/X
+window (regardless of whether that window is active or inactive). This
+prevents the Windows mouse cursor from being placed overtop of the X
+cursor.
+.TP 8
+.B "\-logfile \fIFile_Name\fP"
+Change the log file from the default located at \fI/tmp/XWin.log\fP to
+the one indicated by \fIFile_Name\fP.
+.TP 8
+.B "\-logverbose \fIlevel\fP"
+Control de degree of verbosity of the log messages with the integer
+parameter \fIlevel\fP. For \fIlevel\fP=0  only fatal errors are
+reported, for \fIlevel\fP=1 (default) simple information about
+configuration is also given, for \fIlevel\fP=2 a detailed log
+information (including trace and debug output) is produced. Bigger
+values will yield a still more detailed debug output.
+At this date (April 2004) the option is still not fully operativer; the
+default value is 2 and the output is insensitive to the level value.
+.TP 8
+.B \-multimonitors
+Create a root window that covers all monitors on a system with
+multiple monitors.
+.TP 8
+.B \-multiwindow
+Start the integrated \fIWindowsi\fP-based window manager, which launches each
+top-level X window in its own \fIWindows\fP window. Not to be used together
+with \fB\-rootless\fP nor \fB\-fullscreen\fP.
 .TP 8
 .B \-nodecoration
-Draw the Cygwin/X window without a border or title bar.
+Do not give the Cygwin/X window a Windows window border, title bar,
+etc. This parameter only applies to windowed mode screens, i.e., this
+parameter is ignored when the \fB\-fullscreen\fP parameter is specified.
+.TP 8
+.B \-nounicodeclipboard
+Do not use Unicode clipboard even if NT-based platform.
 .TP 8
-.B \-mwextwm
-Run the server in multi-window external window manager mode.
 .B \-rootless
-Run the server in rootless mode.
+Run the server in rootless mode. Not to be used with \fB\-multiwindow\fP
+nor with \fB\-fullscreen\fP.
 .TP 8
-.B \-lesspointer
-Hide the Windows mouse pointer when over an inactive Cygwin/X window
+.B "\-screen \fIscreen_number\fP \fIwidth\fP \fIheight\fP"
+This parameter may be used to specify the
+.I screen_number,
+.I height,
+and
+.I width
+of one or several Cygwin/X screens; each Cygwin/X screen will be
+opened in its own window. When using multiple screens, be sure not to
+duplicate any screen numbers.
+.I XWin
+default behavior is to create a single screen that is roughly
+the size of the current Windows display area.
+Screen specific parameters, such as \fB\-fullscreen\fP, can be applied as a
+default to all screens by placing those screen specific parameters
+before any \fB\-screen\fP parameter. Screen specific parameters placed after
+the first \fB\-screen\fP parameter will apply only to the immediately
+preceeding \fB\-screen\fP parameter.
 .TP 8
 .B \-scrollbars
 In windowed mode, allow screens bigger than the Windows desktop.
 Moreover, if the window has decorations, one can now resize it.
 .TP 8
-.B "\-clipupdates \fInum_boxes\fP"
-Specify an optional threshold, above which the boxes in a shadow
-update operation will be collected into a GDI clipping region.  The
-clipping region is then used to do a single bit block transfer that is
-constrained to the updated area by the clipping region.  There is some
-overhead involved in creating, installing, destroying, and removing
-the clipping region, thus there may not be much benefit for a small
-number of boxes (less than 10).  It is even possible that this
-functionality does not provide a benefit at any number of boxes; we
-can only determine the usefullness of this feature through testing.
-This parameter works in conjunction with engines 1, 2, and 4 (Shadow
-GDI, Shadow DirectDraw, and Shadow DirectDraw Non-Locking,
-respectively).
-.TP 8
-.B \-emulatepseudo
-Create a depth 8 PseudoColor visual when running in depths 15, 16, 24,
-or 32, collectively known as TrueColor depths.  The PseudoColor visual
-does not have correct colors, and it may crash, but it at least allows
-you to run your PseudoColor application in TrueColor modes.
+.B \-[no]trayicon
+Do not create a tray icon.  Default is to create one
+icon per screen.  You can globally disable tray icons with
+\fB\-notrayicon\fP, then enable it for specific screens with
+\fB\-trayicon\fP for those screens.
 .TP 8
 .B \-[no]unixkill
-Ctrl+Alt+Backspace exits the X Server
+Enable or disable the \fICtrl-Alt-Backspace\fP key combination as a
+signal to exit the X Server. The \fICtrl-Alt-Backspace\fP key combination
+is disabled by default.
 .TP 8
 .B \-[no]winkill
-Alt+F4 exits the X Server
-.SH "SEE ALSO"
+Enable or disable the \fIAlt-F4\fP key combination as a signal to exit the
+X Server.
+The \fIAlt-F4\fP key combination is enabled by default.
+.TP 8
+.B "\-xkblayout \fIlayout\fP"
+.TP 8
+.B "\-xkbmodel \fImodel\fP"
+.TP 8
+.B "\-xkboptions \fIoption\fP"
+.TP 8
+.B "\-xkbrules \fIrule\fP"
+.TP 8
+.B "\-xkbvariant \fIvariant\fp"
+These options implement the xkeyboard extension for loading
+a particular keyboard map as the X server starts.  The behavior is similar
+to the \fIsetxkbmap\fP program. The layout data is located at
+\fI/usr/X11R6/lib/X11/xkb/\fP. Additional information is found in the
+README files therein and in the man page of \fIsetxkbmap\fP. For example
+in order to load a German layout for a pc105 keyboard one uses
+the options:
+.br
+.I " \-xkblayout de \-xkbmodel pc105"
 .PP
-X(__miscmansuffix__), Xserver(1), xdm(1), xinit(1), XWinrc(5)
+Alternatively one may use the \fIsetxkbmap\fP program after XWin is
+running or even the \fIxmodmap\fP program for loading the old-style
+keyboard maps.
+
+
+.SH "SEE ALSO"
+X(__miscmansuffix__), Xserver(1), xdm(1), xinit(1), XWinrc(5), setxkbmap(1)
+
+
 .SH BUGS
 .I XWin
 and this man page still have many limitations. Some of the more obvious
 ones are:
 .br
 - The display mode can not be changed once the X server has started.
-.PP
-.SH AUTHORS
-X was originally ported to Cygwin by Dakshinamurthy Karra,
-Dr. Peter Busch, John Fortin, and Suhaib Siddiqi.
-.I XWin
-is maintained by the Cygwin/X project, with hosting services
-provided by freedesktop.org and RedHat.
-.PP
-The following members, in alphabetical order by last name, of the
-Cygwin/X Team contributed to the X.Org Foundation 6.7 release:
-.PP
-Robert Collins - Cygwin developer, miscellaneous
-.br
-Christopher Faylor - Management of hosting services, general
-programming guru
-.br
-Alexander Gottwald - AltGr handling for non-U.S. keyboards
-.br
-Alan Hourihane - X developer, patch reviewer, general programming guru
-.br
-Pierre A Humblet - Debugging of socket-related crashes, developer
-.br
-Harold L Hunt II - Project leader, lead developer, documentation,
-and website updates
 .br
-Suhaib Siddiqi - Originator of the project
+- The XWin software is developing rapidly; it is therefore likely that
+this man page is not up to date.  It is always prudent to 
+look also at the output of \fIXWin -help\fP and to the Cygwin/X User Guide
+at /usr/share/doc/cygwin-x-doc-x.x.x/ug/cygwin-x-ug.xxx in order to
+check the options that are operative.
+
+
+.SH AUTHORS
+This list is by no means complete, but direct contributors to the
+Cygwin/X project include (in alphabetical order by last name): Stuart
+Adamson, Michael Bax, Jehan Bing, Lev Bishop, Dr. Peter Busch, Biju G
+C, Robert Collins, Nick Crabtree, Early Ehlinger, Christopher Faylor,
+John Fortin, Brian Genisio, Fabrizio Gennari, Alexander Gottwald, Ralf
+Habacker, Colin Harrison, Matthieu Herrb, Alan Hourihane, Pierre A
+Humblet, Harold L Hunt II, Dakshinamurthy Karra, Kensuke Matsuzaki,
+Takuma Murakami, Earle F. Philhower III, Benjamin Riefenstahl, Suhaib
+Siddiqi, Jack Tanner, and Nicholas Wourms.