hashirama/xserver
Watch
0
0
Fork
You've already forked xserver
 0
mirror of https://github.com/X11Libre/xserver.git synced 2026-10-11 23:43:06 +00:00
Code Issues Projects Releases Wiki Activity

XWin: build XWin man pages using XORG_MANPAGE_SECTIONS

Browse source 
Nothing requires the use of a C preprocessor
Using standard file extensions (.man) means no need for .gitignore
Use standard directory and makefile
Now can be built easily on any platform in the man directory

Reviewed-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Reviewed-by: Rémi Cardona <remi@gentoo.org>
Signed-off-by: Gaetan Nadon <memsize@videotron.ca>
Signed-off-by: Keith Packard <keithp@keithp.com>
This commit is contained in:
Gaetan Nadon 2011-01-09 20:27:50 -05:00 • committed by Keith Packard
commit 3f4c71799b
6 changed files with 25 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

21
hw/xwin/man/Makefile.am Normal file
View file

@ -0,0 +1,21 @@
appmandir = $(APP_MAN_DIR)
appman_PRE = XWin.man
appman_DATA = $(appman_PRE:man=$(APP_MAN_SUFFIX))
filemandir = $(FILE_MAN_DIR)
fileman_PRE = XWinrc.man
fileman_DATA = $(fileman_PRE:man=$(FILE_MAN_SUFFIX))
EXTRA_DIST = $(appman_PRE) $(fileman_PRE)
CLEANFILES = $(appman_DATA) $(fileman_DATA)
SUFFIXES = .$(APP_MAN_SUFFIX) .$(FILE_MAN_SUFFIX) .man
# String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure
MAN_SUBSTS += -e 's|__logdir__|$(logdir)|g' \
-e 's|__datadir__|$(datadir)|g' \
-e 's|__sysconfdir__|$(sysconfdir)|g'
.man.$(APP_MAN_SUFFIX):
$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
.man.$(FILE_MAN_SUFFIX):
$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@

346
hw/xwin/man/XWin.man Normal file
View file

@ -0,0 +1,346 @@
.TH XWIN 1 __vendorversion__
.SH NAME
XWin \- X Server for the Cygwin environment on Microsoft Windows
.SH SYNOPSIS
.B XWin
[ options ] ...
.SH DESCRIPTION
\fIXWin\fP is an X Server for the X Window System on the Cygwin environment
running on Microsoft Windows.
.SH MODES
\fIXWin\fP can operate in 3 different modes:
.br
* \fISingle Window\fP: This is the default mode. Each X screen
appears as a single \fIWindows\fP window and all X windows are contained
within this window.
(In X terminology, the \fIWindows\fP window contains the root window for
the screen)
.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 \fIWindows\fP windows.
.br
* \fIRootless\fP: In this mode the X server works in a window
containing the whole screen but this root window (traditionally covered with an X hatch
pattern) is hidden from view, so only top-level X windows are seen.
.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,
\fIall\fP of which are optional:
.SH OPTIONS CONTROLLING WINDOWING MODE
Only one of these options may be specified.
.TP 8
.B (default)
Windowed or rooted mode.
Each X screen appears as a single \fIWindows\fP window and all X windows are
contained within those windows.
.TP 8
.B \-multiwindow
Each top-level X window appears in its own \fIWindows\fP window.
Also start the integrated \fIWindows\fP-based window manager.
.TP 8
.B \-rootless
Run the server in rootless mode.
The X server works on a window covering the whole screen but the root window
is hidden from view.
.TP 8
.B \-mwextwm
Experimental.
The mode combines \fB\-rootless\fP mode drawing with native \fIWindows\fP
window frames managed by the experimental external window manager \fIxwinwm\fP.
.PP
\fBNOTE:\fP \fI-multiwindow\fP mode 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 OPTIONS FOR SPECIFYING X SCREENS
An X display may be composed of multiple screens.
The default behaviour is to create a single screen 0 that is roughly the
size of useful area of the primary monitor (allowing for any window
decorations and the task-bar).
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 \-[no]multimonitors or \-[no]multiplemonitors
Create a screen 0 that covers all monitors [the primary monitor] on a system with
multiple monitors.
This option is currently enabled by default in \fB\-multiwindow\fP mode.
.TP 8
.B "\-screen \fIscreen_number\fP [\fIW\fP \fIH\fP [\fIX\fP \fIY\fP] | [[\fIW\fPx\fIH\fP[+\fIX\fP+\fIY\fP]][@\fIM\fP]] ] "
Create screen number
.I screen_number
and optionally specify it's
.I height,
.I width
and
.I initial position.
Additionally a
.I
monitor number
(which count from 1) can be specified to place the screen on,
at which point, all coordinates become relative to that monitor.
Screen numbers must be contiguous starting from zero and cannot be duplicated.
Examples:
.I " -screen 0 @1 ; on 1st monitor using its full resolution (the default)"
.I " -screen 0 800x600+100+100@2 ; on 2nd monitor offset 100,100 size 800x600"
.I " -screen 0 1024x768@3 ; on 3rd monitor size 1024x768"
.SH OPTIONS CONTROLLING THE APPEARANCE OF THE X SCREEN WINDOWS
These parameters only apply to windowed mode screens i.e. not
in \fB-multwindow\fP or \fB-rootless\fP mode
.TP 8
.B "\-fullscreen"
The X server window takes the full screen, covering completely the
\fIWindows\fP desktop.
.TP 8
.B \-nodecoration
Do not give the Cygwin/X window a \fIWindows\fP window border, title bar,
etc.
This parameter is ignored when the \fB\-fullscreen\fP parameter is specified.
.TP 8
.B \-scrollbars
In windowed mode, allow screens bigger than the \fIWindows\fP desktop.
Moreover, if the window has decorations, one can now resize it.
This parameter is ignored when the \fB\-fullscreen\fP parameter is specified.
.SH OPTIONS CONTROLLING WINDOWS INTEGRATION
.TP 8
.B \-[no]clipboard
Enables [disables] the integration between the Cygwin/X clipboard and
\fIWindows\fP clipboard. The default is enabled.
.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. 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 \-[no]keyhook
Enable [disable] a low-level keyboard hook for catching
special keypresses like Menu and Alt+Tab and passing them to the X
Server instead of letting \fIWindows\fP handle them.
.TP 8
.B \-lesspointer
Normally the \fIWindows\fP mouse cursor is hidden when the mouse is
over an active Cygwin/X window. This option causes the mouse cursor
also to be hidden when it is over an inactive Cygwin/X window. This
prevents the \fIWindows\fP mouse cursor from being drawn on top of the X
cursor.
This parameter has no effect unless \fB-swcursor\fP is also specified.
.TP 8
.B \-swcursor
Disable the usage of the \fIWindows\fP cursor and use the X11 software cursor instead.
.TP 8
.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 \-nounicodeclipboard
Do not use Unicode clipboard even if on a NT-based platform.
.TP 8
.B \-[no]unixkill
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
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.
.SH DRAWING ENGINE OPTIONS
.TP 8
.B "\-clipupdates \fInum_boxes\fP"
Specify an optional threshold, above which the regions 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 option probably has limited effect on current \fIWindows\fP versions
as they already perform GDI batching.
This parameter works in conjunction with engines 1, 2, and 4 (Shadow
GDI, Shadow DirectDraw, and Shadow DirectDraw Non-Locking,
respectively).
.TP 8
.B "\-engine \fIengine_type_id\fP"
This option, which is intended for Cygwin/X developers,
overrides the server's automatically selected 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 DirectDraw Non-Locking.
Additionally, there are engines with type ids
8 - Primary DirectDraw (obsolete) and 16 - Native GDI (experimental and barely functional).
Default behavior is to determine the engine with optimum performance that
supports the specified depth and window configuration.
.SH FULLSCREEN OPTIONS
.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.
.SH MISCELLANEOUS OPTIONS
See also the normal server options described in the \fIXserver(1)\fP
manual page
.TP 8
.B \-help
Write a help text listing supported command line options and their description to the console.
.TP 8
.B \-ignoreinput
Ignore keyboard and mouse input. This is usually only used for testing
and debugging purposes.
.TP 8
.B "\-logfile \fIfilename\fP"
Change the server log file from the default of \fI
__logdir__/XWin.n.log\fP,
where \fIn\fP is the display number of the XWin server, to \fIfilename\fP.
.TP 8
.B "\-logverbose \fIlevel\fP"
Control the 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 simple information about
configuration is also given, for \fIlevel\fP=2 (default)
additional runtime information is recorded
and for \fIlevel\fP=3 detailed log
information (including trace and debug output) is produced. Bigger
values will yield a still more detailed debug output.
.TP 8
.B \-silent-dup-error
If another instance of \fIXWin\fP with the same display number is found running,
exit silently and don't display any error message.
.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 configure the xkeyboard extension to load
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
__datadir__/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"
Alternatively one may use the \fIsetxkbmap\fP program after \fIXWin\fP is
running.
The default is to select a configuration matching your current layout as
reported by \fIWindows\fP, if known, or the default X server configuration
if no matching keyboard configuration was found.
.SH UNDOCUMENTED OPTIONS
These options are undocumented. Do not use them.
.TP 8
.B \-emulatepseudo
Create a depth 8 PseudoColor visual when running in depths 15, 16, 24,
or 32, collectively known as TrueColor depths.
Color map manipulation is not supported, so the PseudoColor visual will
not have the correct colors.
This option is intended to allow applications which only work with a depth 8
visual to operate in TrueColor modes.
.TP 8
.B \-internalwm
Run the internal window manager.
.SH LOG FILE
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
__logdir__/XWin.0.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
__sysconfdir__/X11/system.XWinrc\fP. \fI.XWinrc\fP allows setting
preferences for the following:
.br
* 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
* To include items in the system menu which is associated with the \fIWindows\fP
window that \fIXWin -multiwindow\fP produces for each top-level X
window, in both the generic case and for particular programs.
.br
* To change the icon that is associated to the \fIWindows\fP window that
\fIXWin -multiwindow\fP produces for each top-level X-window.
.br
* To change the style that is associated to the \fIWindows\fP window that
\fXWin I-multiwindow\fP produces for each top-level X window.
.PP
The format of the \fI.XWinrc\fP file is given in the man page XWinrc(5).
.SH EXAMPLES
Need some examples
.SH "SEE ALSO"
X(__miscmansuffix__), Xserver(1), xdm(1), xinit(1), XWinrc(__filemansuffix__), 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.
.br
- The \fIXWin\fP software is continuously developing; it is therefore possible that
this man page is not up to date. It is always prudent to
look also at the output of \fIXWin -help\fP 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, Joe Krahn,
Paul Loewenstein, Kensuke Matsuzaki,
Takuma Murakami, Earle F. Philhower III, Benjamin Riefenstahl, Yaakov Selkowitz,
Suhaib Siddiqi, Jack Tanner, Jon Turney and Nicholas Wourms.

253
hw/xwin/man/XWinrc.man Normal file
View file

@ -0,0 +1,253 @@
.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
__sysconfdir__/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 format
icons \fI.ico\fP.
.PP
4- To change the style that is associated to the \fIWindows\fP window
that \fI-multiwindow\fP produces for each top-level X window. Again,
that can be done both for the generic case and for particular programs.
.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,
or could be parsed, ambiguously, as a misplaced keyword.
.PP
There are four kinds of instructions: miscellaneous, menu, icon and style.
.SH Miscellaneous instruction
.TP 8
.B DEBUG \fIString\fP
The \fIString\fP is printed to the XWin log file.
.TP 8
.B TRAYICON \fIicon-specifier\fB
The \fBTRAYICON\fP keyword changes the icon \fIXWin\fP displays in the
system tray area.
.TP 8
.B SILENTEXIT
The \fBSILENTEXIT\fP keyword, which takes no parameters, disables the
exit confirmation dialog if no clients are connected.
.TP 8
.B FORCEEXIT
The \fBFORCEEXIT\fP keyword, which takes no parameters, disables the
exit confirmation dialog always. Unsaved client work may be lost but
this may be useful if you want no dialogs.
.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 by /bin/sh.
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 specified window class or name
in \fI-multiwindow\fP mode. The keywords ATSTART or ATEND indicate if
such items should be included at the start or at the end of the menu.
.SH Icon Instructions
When specifying an \fIicon-file\fP in the following commands several different formats are allowed:
.br
\fB"NAME.ICO"\fP\fI of an .ico format file\fP
.br
\t \t ("cygwin.ico", "apple.ico")
.br
\fB"NAME.DLL,nn"\fP\fI of a .DLL and icon index\fP
.br
\t \t ("c:\\windows\\system32\\shell32.dll,4" is the default folder icon)
.br
\fB",nnn"\fP\fI index into XWin.EXE internal ICON resources\fP
.br
\t \t (",101" is the 1st icon inside \fIXWin.EXE\fP)
.TP 8
.B ICONDIRECTORY \fIWindows-path-to-icon-directory\fP
Defines the default directory to search for \ficon-file\fP files.
It should be a \fIWindows\fP style path (e.g. C:\\cygwin\\usr\\local\\icons).
.TP 8
.B DEFAULTICON \fIicon-file\fP
Defines a replacement for the standard X icon for applications without
specified icons.
.TP 8
.B ICONS {
.br
\fIclass-or-name-of-window\fP \fIicon-file\fP
.br
\fI...\fP
.br
\fB}\fP
.br
Defines icon replacements windows matching the specified window class or names.
If multiple name or class matches occur for a window, only the first one
will be used.
.SH Style Instructions
.TP 8
.B STYLES {
\fIclass-or-name-of-window\fP \fIstyle-keyword-1\fP \fIstyle-keyword-2\fP
.br
\fI...\fP
.br
\fB}\fP
Associates specific styles to a specified window class or name
in \fI-multiwindow\fP mode. If multiple class or name matches occur,
for a window, only the first one will be used.
The style keywords indicate the following:
\fIstyle-keyword-1\fP
\fBTOPMOST\fP
.br
Open the class or name above all NOTOPMOST Microsoft Windows
.br
\fBMAXIMIZE\fP
.br
Start the class or name fullscreen.
.br
\fBMINIMIZE\fP
.br
Start the class or name iconic.
.br
\fBBOTTOM\fP
.br
Open the class or name below all Windows windows.
.br
\fIstyle-keyword-2\fP
\fBNOTITLE\fP
.br
No Windows title bar, for the class or name.
.br
\fBOUTLINE\fP
.br
No Windows title bar and just a thin-line border, for the class or name.
.br
\fBNOFRAME\fP
.br
No Windows title bar or border, for the class or name.
One keyword in \fIstyle-keyword-1\fP can be used with one keyword in \fIstyle-keyword-2\fP,
or any keyword can be used singly.
.SH EXAMPLE
.TP 8
This example adds an Xterm menu item to the system tray icon
\fBMENU systray {
.br
\t xterm EXEC "xterm -display %display% -sb -sl 999"
.br
\t SEPARATOR
.br
}
.br
ROOTMENU systray
\fP
.TP 8
This example makes an oclock window frameless in \fI-multiwindow\fP mode
\fBSTYLES {
.br
\t oclock NOFRAME
.br
}
.SH "SEE ALSO"
XWin(1)
.SH AUTHOR
The XWinrc feature of XWin was written primarily by Earle F. Philhower
III. Extended for style configuration by Colin Harrison.