diff options
Diffstat (limited to 'libX11/specs/libX11/CH01.xml')
| -rw-r--r-- | libX11/specs/libX11/CH01.xml | 825 |
1 files changed, 825 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH01.xml b/libX11/specs/libX11/CH01.xml new file mode 100644 index 000000000..0e86e7496 --- /dev/null +++ b/libX11/specs/libX11/CH01.xml @@ -0,0 +1,825 @@ +<chapter><title>Introduction to Xlib</title>
+
+<para>
+The X Window System is a network-transparent window system that was designed at MIT. X
+display servers run on computers with either monochrome or color bitmap display hardware. The
+server distributes user input to and accepts output requests from various client programs located
+either on the same machine or elsewhere in the network. Xlib is a C subroutine library that appli-
+cation programs (clients) use to interface with the window system by means of a stream connec-
+tion. Although a client usually runs on the same machine as the X server it is talking to, this need
+not be the case.
+</para>
+<para>
+Xlib − C Language X Interface is a reference guide to the low-level C language interface to the X
+Window System protocol. It is neither a tutorial nor a user’s guide to programming the X Win-
+dow System. Rather, it provides a detailed description of each function in the library as well as a
+discussion of the related background information. Xlib − C Language X Interface assumes a
+basic understanding of a graphics window system and of the C programming language. Other
+higher-level abstractions (for example, those provided by the toolkits for X) are built on top of the
+Xlib library. For further information about these higher-level libraries, see the appropriate toolkit
+documentation. The X Window System Protocol provides the definitive word on the behavior of
+X. Although additional information appears here, the protocol document is the ruling document.
+</para>
+<para>
+To provide an introduction to X programming, this chapter discusses:
+</para>
+
+<itemizedlist>
+ <listitem><para>Overview of the X Window System</para></listitem>
+ <listitem><para>Errors</para></listitem>
+ <listitem><para>Standard header files</para></listitem>
+ <listitem><para>Generic values and types</para></listitem>
+ <listitem><para>Naming and argument conventions within Xlib</para></listitem>
+ <listitem><para>Programming considerations</para></listitem>
+ <listitem><para>Character sets and encodings</para></listitem>
+ <listitem><para>Formatting conventions</para></listitem>
+</itemizedlist>
+
+
+<sect1 id="Overview_of_the_X_Window_System">
+<title>Overview of the X Window System</title>
+<!-- .XS -->
+<!-- (SN Overview of the X Window System -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some of the terms used in this book are unique to X,
+and other terms that are common to other window systems
+have different meanings in X.
+You may find it helpful to refer to the glossary,
+which is located at the end of the book.
+</para>
+<para>
+<!-- .LP -->
+The X Window System supports one or more screens containing
+overlapping windows or subwindows.
+A screen is a physical monitor and hardware
+that can be color, grayscale, or monochrome.
+There can be multiple screens for each display or workstation.
+A single X server can provide display services for any number of screens.
+A set of screens for a single user with one keyboard and one pointer
+(usually a mouse) is called a display.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Screen</primary></indexterm>
+All the windows in an X server are arranged in strict hierarchies.
+At the top of each hierarchy is a root window,
+which covers each of the display screens.
+Each root window is partially or completely covered by child windows.
+All windows, except for root windows, have parents.
+There is usually at least one window for each application program.
+<indexterm><primary>Child window</primary></indexterm>
+<indexterm><primary>Parent Window</primary></indexterm>
+Child windows may in turn have their own children.
+In this way,
+an application program can create an arbitrarily deep tree
+on each screen.
+X provides graphics, text, and raster operations for windows.
+</para>
+<para>
+<!-- .LP -->
+A child window can be larger than its parent.
+That is, part or all of
+the child window can extend beyond the boundaries of the parent,
+but all output to a window is clipped by its parent.
+<indexterm><primary>Stacking order</primary></indexterm>
+If several children of a window have overlapping locations,
+one of the children is considered to be on top of or raised over the
+others, thus obscuring them.
+Output to areas covered by other windows is suppressed by the window
+system unless the window has backing store.
+If a window is obscured by a second window,
+the second window obscures only those ancestors of the second window
+that are also ancestors of the first window.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Window</primary></indexterm>
+A window has a border zero or more pixels in width, which can
+be any pattern (pixmap) or solid color you like.
+A window usually but not always has a background pattern,
+which will be repainted by the window system when uncovered.
+Child windows obscure their parents,
+and graphic operations in the parent window usually
+are clipped by the children.
+</para>
+<para>
+<!-- .LP -->
+Each window and pixmap has its own coordinate system.
+The coordinate system has the X axis horizontal and the Y axis vertical
+with the origin [0, 0] at the upper-left corner.
+Coordinates are integral,
+in terms of pixels,
+and coincide with pixel centers.
+For a window,
+the origin is inside the border at the inside, upper-left corner.
+</para>
+<para>
+<!-- .LP -->
+X does not guarantee to preserve the contents of windows.
+When part or all of a window is hidden and then brought back onto the screen,
+its contents may be lost.
+The server then sends the client program an
+<function>Expose</function>
+event to notify it that part or all of the window needs to be repainted.
+Programs must be prepared to regenerate the contents of windows on demand.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Pixmap</primary></indexterm>
+<indexterm><primary>Drawable</primary></indexterm>
+<indexterm><primary>Tile</primary></indexterm>
+<indexterm><primary>Bitmap</primary></indexterm>
+X also provides off-screen storage of graphics objects,
+called pixmaps.
+Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.
+Pixmaps can be used in most graphics functions interchangeably with
+windows and are used in various graphics operations to define patterns or tiles.
+Windows and pixmaps together are referred to as drawables.
+</para>
+<para>
+<!-- .LP -->
+Most of the functions in Xlib just add requests to an output buffer.
+These requests later execute asynchronously on the X server.
+Functions that return values of information stored in
+the server do not return (that is, they block)
+until an explicit reply is received or an error occurs.
+You can provide an error handler,
+which will be called when the error is reported.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>XSync</primary></indexterm>
+If a client does not want a request to execute asynchronously,
+it can follow the request with a call to
+<function>XSync</function>,
+which blocks until all previously buffered
+asynchronous events have been sent and acted on.
+As an important side effect,
+the output buffer in Xlib is always flushed by a call to any function
+that returns a value from the server or waits for input.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Resource IDs</primary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm>
+Many Xlib functions will return an integer resource ID,
+which allows you to refer to objects stored on the X server.
+These can be of type
+<function>Window</function>,
+<function>Font</function>,
+<function>Pixmap</function>,
+<function>Colormap</function>,
+<function>Cursor</function>,
+and
+<function>GContext</function>,
+as defined in the file
+<!-- .hN X11/X.h . -->
+These resources are created by requests and are destroyed
+(or freed) by requests or when connections are closed.
+Most of these resources are potentially sharable between
+applications, and in fact, windows are manipulated explicitly by
+window manager programs.
+Fonts and cursors are shared automatically across multiple screens.
+Fonts are loaded and unloaded as needed and are shared by multiple clients.
+Fonts are often cached in the server.
+Xlib provides no support for sharing graphics contexts between applications.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Event</primary></indexterm>
+Client programs are informed of events.
+Events may either be side effects of a request (for example, restacking windows
+generates
+<function>Expose </function>
+events) or completely asynchronous (for example, from the keyboard).
+A client program asks to be informed of events.
+Because other applications can send events to your application,
+programs must be prepared to handle (or ignore) events of all types.
+</para>
+<para>
+<!-- .LP -->
+Input events (for example, a key pressed or the pointer moved)
+arrive asynchronously from the server and are queued until they are
+requested by an explicit call (for example,
+<function>XNextEvent</function>
+or
+<function>XWindowEvent</function>).
+In addition, some library
+functions (for example,
+<function>XRaiseWindow</function>)
+generate
+<function>Expose</function>
+and
+<function>ConfigureRequest</function>
+events.
+These events also arrive asynchronously, but the client may
+<indexterm><primary>XSync</primary></indexterm>
+wish to explicitly wait for them by calling
+<function>XSync</function>
+after calling a function that can cause the server to generate events.
+</para>
+</sect1>
+<sect1 id="Errors">
+<title>Errors</title>
+<!-- .XS -->
+<!-- (SN Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some functions return
+<function>Status</function>,
+an integer error indication.
+If the function fails, it returns a zero.
+If the function returns a status of zero,
+it has not updated the return arguments.
+<indexterm><primary>Status</primary></indexterm>
+Because C does not provide multiple return values,
+many functions must return their results by writing into client-passed storage.
+<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm>
+By default, errors are handled either by a standard library function
+or by one that you provide.
+Functions that return pointers to strings return NULL pointers if
+the string does not exist.
+</para>
+<para>
+<!-- .LP -->
+The X server reports protocol errors at the time that it detects them.
+If more than one error could be generated for a given request,
+the server can report any of them.
+</para>
+<para>
+<!-- .LP -->
+Because Xlib usually does not transmit requests to the server immediately
+(that is, it buffers them), errors can be reported much later than they
+actually occur.
+For debugging purposes, however,
+Xlib provides a mechanism for forcing synchronous behavior
+(see section 11.8.1). <!-- xref -->
+When synchronization is enabled,
+errors are reported as they are generated.
+</para>
+<para>
+<!-- .LP -->
+When Xlib detects an error,
+it calls an error handler,
+which your program can provide.
+If you do not provide an error handler,
+the error is printed, and your program terminates.
+</para>
+</sect1>
+<sect1 id="Standard_Header_Files">
+<title>Standard Header Files</title>
+<!-- .XS -->
+<!-- (SN Standard Header Files -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following include files are part of the Xlib standard:
+</para>
+<!-- .IP \(bu 5 -->
+<!-- .hN X11/Xlib.h -->
+<!-- .IP -->
+
+<variablelist>
+ <varlistentry>
+ <term></X11/Xlib.h></term>
+ <listitem>
+ <para>
+This is the main header file for Xlib.
+The majority of all Xlib symbols are declared by including this file.
+This file also contains the preprocessor symbol
+<function>XlibSpecificationRelease</function>.
+<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm>
+This symbol is defined to have the 6 in this release of the standard.
+(Release 5 of Xlib was the first release to have this symbol.)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/X.h></term>
+ <listitem>
+ <para>
+This file declares types and constants for the X protocol that are
+to be used by applications. It is included automatically from
+>X11/Xlib.h< so application code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xcms.h></term>
+ <listitem>
+ <para>
+This file contains symbols for much of the color management facilities
+described in chapter 6. All functions, types, and symbols with the
+prefix "Xcms", <!-- xref -->
+plus the Color Conversion Contexts macros, are declared in this file.
+<X11/Xlib.h> must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xutil.h></term>
+ <listitem>
+ <para>
+This file declares various functions, types, and symbols used for
+inter-client communication and application utility functions,
+which are described in chapters 14 and 16. <!-- xref -->
+<X11/Xlib.h> must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xresource.h></term>
+ <listitem>
+ <para>
+This file declares all functions, types, and symbols for the
+resource manager facilities, which are described in chapter 15.
+<X11/Xlib.h> <!-- xref -->
+must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xatom.h></term>
+ <listitem>
+ <para>
+This file declares all predefined atoms,
+which are symbols with the prefix "XA_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/cursorfont.h></term>
+ <listitem>
+ <para>
+This file declares the cursor symbols for the standard cursor font,
+which are listed in appendix B.
+All cursor symbols have the prefix "XC_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/keysymdef.h></term>
+ <listitem>
+ <para>
+This file declares all standard KeySym values,
+which are symbols with the prefix "XK_".
+The KeySyms are arranged in groups, and a preprocessor symbol controls
+inclusion of each group. The preprocessor symbol must be defined
+prior to inclusion of the file to obtain the associated values.
+The preprocessor symbols are <function>XK_MISCELLANY, XK_XKB_KEYS, XK_3270,
+XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC,
+XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL,
+XK_HEBREW, XK_THAI, and XK_KOREAN</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/keysym.h></term>
+ <listitem>
+ <para>
+This file defines the preprocessor symbols
+XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3,
+XK_LATIN4, and XK_GREEK
+and then includes <X11/keysymdef.h>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xlibint.h></term>
+ <listitem>
+ <para>
+This file declares all the functions, types, and symbols used for
+extensions, which are described in appendix C.
+This file automatically includes
+<X11/Xlib.h<.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xproto.h></term>
+ <listitem>
+ <para>
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+<X11/Xlibint.h<,
+so application and extension code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/Xprotostr.h></term>
+ <listitem>
+ <para>
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+<X11/Xproto.h<,
+so application and extension code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><X11/X10.h></term>
+ <listitem>
+ <para>
+This file declares all the functions, types, and symbols used for the
+X10 compatibility functions, which are described in appendix D.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect1>
+
+
+
+<sect1 id="Generic_Values_and_Types">
+<title>Generic Values and Types</title>
+<!-- .XS -->
+<!-- (SN Generic Values and Types -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following symbols are defined by Xlib and used throughout the manual:
+<indexterm significance="preferred"><primary>Bool</primary></indexterm>
+<indexterm significance="preferred"><primary>True</primary></indexterm>
+<indexterm significance="preferred"><primary>False</primary></indexterm>
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Xlib defines the type
+<function>Bool</function>
+and the Boolean values
+<function>True</function>
+and
+<function>False</function>.
+<indexterm significance="preferred"><primary>None</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>None</function>
+is the universal null resource ID or atom.
+<indexterm significance="preferred"><primary>XID</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The type
+<function>XID</function>
+is used for generic resource IDs.
+<indexterm significance="preferred"><primary>XPointer</primary></indexterm>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The type
+<function>XPointer</function>
+is defined to be char\^* and is used as a generic opaque pointer to data.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Naming_and_Argument_Conventions_within_Xlib">
+<title>Naming and Argument Conventions within Xlib</title>
+<!-- .XS -->
+<!-- (SN Naming and Argument Conventions within Xlib -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib follows a number of conventions for the naming and syntax of the functions.
+Given that you remember what information the function requires,
+these conventions are intended to make the syntax of the functions more
+predictable.
+</para>
+<para>
+<!-- .LP -->
+The major naming conventions are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+To differentiate the X symbols from the other symbols,
+the library uses mixed case for external symbols.
+It leaves lowercase for variables and all uppercase for user macros,
+as per existing convention.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All Xlib functions begin with a capital X.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The beginnings of all function names and symbols are capitalized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All user-visible data structures begin with a capital X.
+More generally,
+anything that a user might dereference begins with a capital X.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Macros and other symbols do not begin with a capital X.
+To distinguish them from all user symbols,
+each word in the macro is capitalized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All elements of or variables in a data structure are in lowercase.
+Compound words, where needed, are constructed with underscores (_).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The display argument, where used, is always first in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All resource objects, where used, occur at the beginning of the argument list
+immediately after the display argument.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a graphics context is present together with
+another type of resource (most commonly, a drawable), the
+graphics context occurs in the argument list after the other
+resource.
+Drawables outrank all other resources.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Source arguments always precede the destination arguments in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The x argument always precedes the y argument in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The width argument always precedes the height argument in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Where the x, y, width, and height arguments are used together,
+the x and y arguments always precede the width and height arguments.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Where a mask is accompanied with a structure,
+the mask always precedes the pointer to the structure in the argument list.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Programming_Considerations">
+<title>Programming Considerations</title>
+<!-- .XS -->
+<!-- (SN Programming Considerations -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The major programming considerations are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Coordinates and sizes in X are actually 16-bit quantities.
+This decision was made to minimize the bandwidth required for a
+given level of performance.
+Coordinates usually are declared as an
+<function>int </function>
+in the interface.
+Values larger than 16 bits are truncated silently.
+Sizes (width and height) are declared as unsigned quantities.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keyboards are the greatest variable between different
+manufacturers' workstations.
+If you want your program to be portable,
+you should be particularly conservative here.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Many display systems have limited amounts of off-screen memory.
+If you can, you should minimize use of pixmaps and backing
+store.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The user should have control of his screen real estate.
+Therefore, you should write your applications to react to window management
+rather than presume control of the entire screen.
+What you do inside of your top-level window, however,
+is up to your application.
+For further information,
+see chapter 14 <!-- xref -->
+and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Character_Sets_and_Encodings">
+<title>Character Sets and Encodings</title>
+<!-- .XS -->
+<!-- (SN Character Sets and Encodings -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some of the Xlib functions make reference to specific character sets
+and character encodings.
+The following are the most common:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+X Portable Character Set
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A basic set of 97 characters,
+which are assumed to exist in all locales supported by Xlib.
+This set contains the following characters:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+This set is the left/lower half
+of the graphic character set of ISO8859-1 plus space, tab, and newline.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Host Portable Character Encoding
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The encoding of the X Portable Character Set on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Latin-1
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The coded character set defined by the ISO8859-1 standard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Latin Portable Character Encoding
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+STRING Encoding
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Latin-1, plus tab and newline.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<acronym>POSIX</acronym> Portable Filename Character Set
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The set of 65 characters,
+which can be used in naming files on a <acronym>POSIX</acronym>-compliant host,
+that are correctly processed in all locales.
+The set is:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literallayout class="monospaced">
+a..z A..Z 0..9 ._-
+</literallayout>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id="Formatting_Conventions">
+<title>Formatting Conventions</title>
+<!-- .XS -->
+<!-- (SN Formatting Conventions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<emphasis remap='I'>Xlib \- C Language X Interface</emphasis> uses the following conventions:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Global symbols are printed in
+<function>this </function>
+<function>special </function>
+<function>font</function>.
+These can be either function names,
+symbols defined in include files, or structure names.
+When declared and defined,
+function arguments are printed in <emphasis remap='I'>italics</emphasis>.
+In the explanatory text that follows,
+they usually are printed in regular type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Each function is introduced by a general discussion that
+distinguishes it from other functions.
+The function declaration itself follows,
+and each argument is specifically explained.
+Although ANSI C function prototype syntax is not used,
+Xlib header files normally declare functions using function prototypes
+in ANSI C environments.
+General discussion of the function, if any is required,
+follows the arguments.
+Where applicable,
+the last paragraph of the explanation lists the possible
+Xlib error codes that the function can generate.
+For a complete discussion of the Xlib error codes,
+see section 11.8.2. <!-- xref -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To eliminate any ambiguity between those arguments that you pass and those that
+a function returns to you,
+the explanations for all arguments that you pass start with the word
+<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify\^</emphasis>.
+The explanations for all arguments that are returned to you start with the
+word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return\^</emphasis>.
+The explanations for all arguments that you can pass and are returned start
+with the words <emphasis remap='I'>specifies and returns\^</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Any pointer to a structure that is used to return a value is designated as
+such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
+All other pointers passed to these functions are
+used for reading only.
+A few arguments use pointers to structures that are used for
+both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix.
+<!-- .bp -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+</chapter>
|