README.md revision d63b911f 
1X Window System Unified Protocol
2--------------------------------
3
4This package provides the headers and specification documents defining
5the core protocol and (many) extensions for the X Window System. The
6extensions are those common among servers descended from X11R7. It
7also includes a number of headers that aren't purely protocol related,
8but are depended upon by many other X Window System packages to provide
9common definitions and porting layer.
10
11Though the protocol specifications herein are authoritative, the
12content of the headers is bound by compatibility constraints with older
13versions of the X11 suite. If you are looking for a machine-readable
14protocol description suitable for code generation or use in new
15projects, please refer to the XCB project:
16
17  https://xcb.freedesktop.org/
18  https://gitlab.freedesktop.org/xorg/proto/xcbproto
19
20All questions regarding this software should be directed at the
21Xorg mailing list:
22
23  https://lists.x.org/mailman/listinfo/xorg
24
25The primary development code repository can be found at:
26
27  https://gitlab.freedesktop.org/xorg/proto/xorgproto
28
29Please submit bug reports and requests to merge patches there.
30
31For patch submission instructions, see:
32
33  https://www.x.org/wiki/Development/Documentation/SubmittingPatches
34
35
36Updating for new Linux kernel releases
37--------------------------------------
38
39The XF86keysym.h header file needs updating whenever the Linux kernel
40adds a new keycode to linux/input-event-codes.h. See the comment in
41include/X11/XF86keysym.h for details on the format.
42
43The steps to update the file are:
44
45- if the kernel release did not add new `KEY_FOO` defines, no work is
46  required
47- ensure that libevdev has been updated to the new kernel headers. This may
48  require installing libevdev from git.
49- run `scripts/keysym-generator.py` to add new keysyms. See the `--help`
50  output for the correct invocation.
51- verify that the format for any keys added by this script is correct and
52  that the keys need to be mapped. Where a key code should not get a new
53  define or is already defined otherwise, comment the line.
54- file a merge request with the new changes
55- notify the xkeyboard-config maintainers that updates are needed
56
57Note that any #define added immediately becomes API. Due diligence is
58recommended.
59