Documentation?

[Glynn Clements]

Patrick O'Donnell wrote:

> >> Someone offered up www.x.org/docs, which may be fine for X Window
> >> System developers, but is not what most application programmers would
> >> call documentation.
> >
> >Oh? Would you care to elaborate? Like, what is *actually* missing?
> 
> The first thing to come to mind is a guide to what's even in that
> directory.  If you already know what all the abbreviations and
> initializms are, then you can probably find what you're looking for
> without too much trouble.  If not, it's pretty much hit-and-miss.

Okay.

BDF	Bitmap Distribution Format

	Format of BDF bitmap font files

CTEXT	Compound Text Encoding

	ISO-2022-based encoding used for transferring multi-lingual
	text between applications. Corresponds to COMPOUND_TEXT type
	atom. Newer toolkits and applications often use UTF-8 instead.

FSProtocol	Font Server Protocol

	Communication between font servers and the X server.

ICCCM	Inter-Client Communication Conventions Manual

	Properties and messages used for communication between
	applications and the WM and other applications, including
	selections and clipboard.

ICE	Inter-Client Exchange Library

	Framework to simplify building inter-client protocols.

RX	Remote Execution

	Embedding X applications in a web browser.

SM	Session Management

	Save and restore desktop sessions

X11	Xlib Reference Manual

XDMCP	X Display Manager Control Protocol

	Managing a network of X terminals using a single display
	manager.

XIM	X Input Method Protocol

	Communication between input method servers and clients

XKB	X Keyboard Extension

	Library and protocol for querying and configuring keyboard
	layout and behaviour.

XLFD	X Logical Font Description Conventions

	Structure of core font names and wildcards.

XPRINT	X Print Service Extension

	Library and protocol for printing

XProtocol	X Protocol

	The core X11 protocol

Xaw	Athena Widget Set

	Widget set for use with the X toolkit (Xt)

Xext	Miscellaneous Extensions

	Various extensions which are bundled into a single server
	module (extmod). Includes DPMS, shaped windows, shared-memory
	images, security.

Xi	X Input Device Extension

	Support for additional input devices beyond pointer and keyboard.

Xmu	X Miscellaneous Utilities

	Miscellaneous utility functions which don't fit anywhere else.

Xserver	X Server Internals

	X Server internals and implementation details

Xt	X Toolkit Intriniscs

	A GUI toolkit. Used in conjunction with the Athena (Xaw) and
	Motif (Xm) widget sets.

Xv	X Video Extension

	Video capture and playback. Supports the use of hardware video
	overlays using e.g. YUV-4:2:0 format.

i18n	Internationalisation

	Related to XIM (above)

man	Manual

	PostScript/PDF versions of X manual pages.

rstart	A Flexible Remote Execution Protocol Based on rsh

	Start X applications on a remote server for local display.

saver	X Screen Saver Extension

	For writing screen savers.

xfs	Font Server Implementation Overview

	xfs internals

xterm	XTerm Control Sequences

	Control and escape sequences supported by XTerm

xtrans	X Transport Interface

	Abstraction layer around various low-level transport layers (BSD
	sockets, TLI, etc).

The most important ones are Xlib and ICCCM. Several of the above are
legacy interfaces which aren't relevant to modern toolkits.

In theory, most of the above aren't relevant if you're using such
toolkits; you should only need to read the toolkit's documentation
(e.g. GTK+ applications are supposed to use GDK for rendering rather
than using Xlib directly).

If you're using Xt+Xaw/Xm, those toolkits rely upon many of the above. 
Some of it is hidden from the user, some of it is exposed.

Writing a GUI application using nothing but raw Xlib is a bad idea. 
It's analogous to writing an application without any libraries (even
libc), using nothing but home-grown functions and direct system calls.

> Also, something to glue all the pieces together -- to tell the
> application programmer where each piece fits in the whole puzzle,
> where to use it, when to use it, and equally important, when not to.
> Something like the old Xlib Programmer's Guide.  Reference information
> where you must infer the API from protocol specs is hard enough to
> grok.  Trying to put together a coherent big picture from the
> scattered bits takes a lot of time that someone trying to get a
> product out the door doesn't have.

Application programming documentation normally focuses on a specific
toolkit. The toolkit will hide most of the details, particularly if it
is cross-platform. The low-level documentation is of interest mainly
to authors of toolkits and/or low-level utilities.

-- 
Glynn Clements <glynn at gclements.plus.com>